Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#21558 closed Bug (fixed)

Build CHM help file format out of box on win32

Reported by: Michał Pasternak Owned by: nobody
Component: Documentation Version: 1.6
Severity: Normal Keywords: html help chm generation docs
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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

Change History (10)

comment:1 by Michał Pasternak, 10 years ago

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!

comment:2 by Ramiro Morales, 10 years ago

Triage Stage: UnreviewedAccepted

comment:3 by Michał Pasternak, 10 years ago

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

comment:4 by Aymeric Augustin, 10 years ago

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.

comment:5 by Michał Pasternak, 10 years ago

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!

comment:6 by Aymeric Augustin <aymeric.augustin@…>, 10 years ago

Resolution: fixed
Status: newclosed

In cd9e85ece94214718257d972e9e5ab4bac3f0e65:

Fixed #21558 -- Support building CHM files.

Thanks Michał Pasternak.

comment:7 by Aymeric Augustin <aymeric.augustin@…>, 10 years ago

In deeed42253edf583974662657c70014d1634b46b:

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

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

comment:8 by Aymeric Augustin <aymeric.augustin@…>, 10 years ago

In 6691abcdf0db219bfa584d52eb21e891d88f2aeb:

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

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

comment:9 by Aymeric Augustin <aymeric.augustin@…>, 10 years ago

In 2d4f399ad40c63bbfd7917a9f2006f4ebb495099:

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

Thanks Michał Pasternak.

Backport of cd9e85ec from master.

comment:10 by Michał Pasternak, 10 years ago

THANKS MAN!

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

Note: See TracTickets for help on using tickets.
Back to Top