04 June 2012

Django 1.4 help file CHM version (and how to build your own)

UPDATE 2012-06-04: God save the Queen! Thanks to the long "Jubilee Holiday Weekend", I got around generating an updated version for Django 1.4. Here it is: Djangodocs 1.4 in CHM format. Enjoy!

----------

This is a funny story.

I happen to think Microsoft's proprietary CHM format is lovely. So I went looking for a CHM version of docs for Django, and google found it for me on this blog. I duly downloaded it, tried to to open it and... it wouldn't display. I could only see the TOC, but not the actual documents. I thought this might be a corrupted version, and it was for an alpha release of Django anyway, so I though I'd compile a version myself. After all, these docs are built with Sphinx, which apparently can generate all sorts of formats...

So here's the procedure to compile django's docs:

  1. download and install Sphinx.
    Easy_install Sphinx
    was all I needed. Hurrah for Python.
  2. ADDITIONAL STEP for v1.4: modify _theme\djangodocs\layout.html to remove all javascript tags, otherwise you'll get jQuery-related errors in the final output. This is a known bug.
  3. Run Sphinx to generate the initial files:
    cd Django-1.1/docs
    mkdir _build/html
    %PYTHONDIR%\scripts\sphinx-build.exe -b htmlhelp -d _build\doctrees . _build\html
    
  4. Download and install Htmlhelp.exe from the Microsoft site. This will give you the HTML Help Workshop. Note: it doesn't matter if you get a final message saying you already have a more recent version.
  5. launch the workshop, File -> Compile..., select the file Djangodoc.hhc which should now be in _build/html, and this will produce the chm.
  6. ...??? Profit!

... Then I found out the reason that downloaded CHM didn't work was a stupid patch from Microsoft. Ouch.

Anyway, if you need it, here's the file: Djangodocs 1.1 in CHM format. If it doesn't work, make sure you follow this suggested procedure, and save yourself some time...

6 comments:

Giulio Piancastelli said...

Well, nice, but it would be even more interesting to know why you think that CHM is a lovely format for deploying offline documentation.

GiacomoL said...

The index/search/TOC combo is simply a killer, IMHO. You don't get that with simple HTML, nor with PDF.

Anonymous said...

THANKS! FOR THE CHM!

Anonymous said...

Awesome! Thx, I alos love the CHM format for offline browsing ... well, easy_install doesn't work well on my nasty windows system. So I would be sooo happy, if you could provide a CHM version of the latest Django 1.2 :-))

Sincerely, Simon

abc said...

I'd like to say thank you for your work.
I agree with you that index/search/TOC is very very important

MichaƂ Pasternak said...

Hi,

as issue https://code.djangoproject.com/ticket/21558 was fixed, the documentation should work out-of-box now: get django sources, get sphinx, "make htmlhelp", then use Microsoft Help Compiler. No need to modify layout.html template.