Sphinx and htmlhelp

I remember when I went to do a release of Stackless Python and as usual I went to make a futile attempt at building the documentation, and found that the documentation generation I could never get to work on Windows had been replaced. I still find the new Python documentation generation, based on sphinx, to be inspirational. Being able to go make checkout and have sphinx and its dependencies fetched, and then to be able to go make htmlhelp or just make html and to have the respective format of documentation generated with minimal extra work.. it is just a pleasure. However, there are some little bits and pieces I would like to note related to the generation of the htmlhelp format documents.

HTML Help Workshop

In order to generate the .chm files, you need to have the HTML Help Workshop installed. I don't know how this is done with just sphinx, but when you are generating the Python documentation the make script takes care of assuming the presence of a default installation location.

if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe

64 bit Windows users like myself will find that %ProgramFiles% actually resolves to C:\Program Files\ which is all well and good, but HTML Help Workshop is a 32 bit program and therefore it gets installed to C:\Program Files (x86)\. You can replace that line with the following lines.

REM Find the 32 bit Program Files directory.
set PFA=%ProgramFiles%
if not "%ProgramFiles(x86)%" == "" set PFA=%ProgramFiles(x86)%

REM Set defaults for non-existent environment variables.
if "%HTMLHELP%" EQU "" set HTMLHELP=%PFA%\HTML Help Workshop\hhc.exe

Compilation failed while compiling index.html

I adapted the make.bat script that comes in the Python Doc directory to build documentation for my own project. But when I tried to run HTML Help Workshop on the .hhp file that sphinx generated, it exited claiming "Compilation failed while compiling index.html". This is a file that sphinx tells hhc.exe to use, but where does it come from? Beats me, I tried searching but in the end went back to where the Python generation gets its version. It does the following.

1. Adding a

   templates_path = [ "templates" ]

   statement to the conf.py file.
2. Adding a

   html_additional_pages = {
       "index": "index.html",
   }

   statement to the conf.py file.
3. Making a templates directory in the same directory as the conf.py file.
4. Put a blank file named index.html in the templates directory.

This means that index.html will be looked for in the templates directory, and it will be used to generate an index page. This index page maps to a generated index.html file within (in my case) the directory build/htmlhelp/index.html. How should templates/index.html be fleshed out? No idea, but hopefully the sphinx documentation addresses that and if not, I should hopefully be able to again use the files in the Python Doc directory as a guide.