Build CHM help file format out of box on win32

[Michał Pasternak]

Hi,

CHM file format is Microsoft Help file Compiled HTML Help format and for me and perhaps some other people, it is very convinient to use it[1]. In the past, various individuals([2], [3]) built their own, unofficial CHM files by hand. Also, there are other projects, not less prominent, than ours beloved Django ([4], [5], [6]), who happily provide CHM help on their official pages.

So, why aren't we doing that? Let's fix this now.

For the CHM help file building... why do it by hand, when we are already using Makefiles to build documentation?

Modify the Makefile... done!

Another problem: the files compiled by Sphinx can not be feed to Microsoft Help Compiler, because of included JQuery (https://code.djangoproject.com/ticket/14950), which caused errors on every page opened. This is relativley easy to fix, by using sphinx-build command line switch -A, which feeds variables directly to template rendering context.

So, in the commit linked to this issue, I am fixing both 14950 _and_ I am including call to Microsoft Help Compiler, to build the required CHM file, so perhaps in the future our project would be able to provide CHM help files for those win32-based djangonauts out there. And, the make.bat contains a link to Microsoft Help Compiler download, if anybody does need that.

The errorlevel checking part is a bit strange for anybody using a regular shell like bash or zsh, it is explained here [7].

So, what do you say, guys? I will include the patch in the comment as soon as I add this issue to tracker, so I can use its number in the commit...

Links:

1. Comments below this article ​http://blog.pythonaro.com/2009/08/django-11-help-file-chm-version.html for example
2. ​http://www.aryehleib.com/CHM.html
3. ​http://blog.pythonaro.com/2009/08/django-11-help-file-chm-version.html
4. ​http://php.net/download-docs.php
5. ​http://rubyinstaller.org/downloads/
6. ​http://python.org/download/releases/2.7.6/
7. ​http://www.incodesystems.com/PRODUCTS/ERRORLE1.HTM

[Michał Pasternak]

And, here's the simple fix from yours truly: ​https://github.com/mpasternak/django/commit/1336d8f8599f8d0571893c0bbd03f52f66eb36ef . It is for stable/1.6.x, as I need CHM documentation for this particular version, but it should be the same patch for the master branch.

What do you say?

PS: thank you, thank you, thank you for a GREATEST WEB FRAMEWORK of ALL TIME. ALL TIME!

[Michał Pasternak]

Hi,

my original patch was too complicated. As @apollo13 pointed out on IRC, I can use builder variable in jinja context, so:

​https://github.com/mpasternak/django/commit/c06cd4f95b7051da86c29320f069d06187d54792

[Aymeric Augustin]

The change to the documentation template is a good idea.

I'm less sure about the change to make.bat, how is it specific to Django? If it isn't, it should be made in Sphinx itself, since make.bat is generated by Sphinx.

[Michał Pasternak]

I agree about changes to make.bat . They may be lost during the next run of sphinx tools, the file is autogenerated, so there is no point in patching it really. I created an issue for Sphinx ​https://bitbucket.org/birkenfeld/sphinx/issue/1318/compile-chm-files-out-of-box-on-windows and the fix ​https://bitbucket.org/birkenfeld/sphinx/pull-request/195/compile-chm-files-out-of-box/diff#chg-sphinx/quickstart.py and it is not really so trival thing to fix properly because of strange Microsoft Windows shell problems here ​http://www.blinnov.com/en/2010/06/04/microsoft-was-unexpected-at-this-time/ .

If you think we should add the part that detects the builder and omits jquery, I'd be more than happy.

Thank You!

[Aymeric Augustin <aymeric.augustin@…>]

In cd9e85ece94214718257d972e9e5ab4bac3f0e65:

Fixed #21558 -- Support building CHM files.

Thanks Michał Pasternak.

[Aymeric Augustin <aymeric.augustin@…>]

In deeed42253edf583974662657c70014d1634b46b:

[1.5.x] Fixed #21558 -- Support building CHM files.

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

[Aymeric Augustin <aymeric.augustin@…>]

In 6691abcdf0db219bfa584d52eb21e891d88f2aeb:

[1.6.x] Fixed #21558 -- Support building CHM files.

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

[Aymeric Augustin <aymeric.augustin@…>]

In 2d4f399ad40c63bbfd7917a9f2006f4ebb495099:

[1.4.x] Fixed #21558 -- Support building CHM files.

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

[Michał Pasternak]

THANKS MAN!

I think we can close https://code.djangoproject.com/ticket/14950 too.