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...


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...


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...


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.