How to create a single file of Sphinx based documentation

It has become common nowadays that Python projects provide their documentation in “source form“. The documentation is split into multiple files, written in restructured text, and is shipped together with some other configuration and media files for Sphinx. The user is meant to use the provided Makefile to export the documentation in various formats. This is good and useful. Sphinx generates some nice and very readable HTML files. The only problem I encountered today was that the provided Makefile or make.bat batch script (for Windows) cannot be used to generate a single file containing the whole documentation of the project. At first, it seemed that in order to print the whole documentation I should either:

• export the documentation into multiple HTML files using make html and then send the relevant html files one-by-one to the printer, which is insanely inconvenient, or
• export the documentation to LaTeX format and then use a tex-to-pdf converter in order to merge the documentation files into a single file, which I would finally send to the printer. It should be noted that in this case, the tex-to-pdf converter had some other dependencies which summed up to 130+MB. Compressed. That’s insanely too much for converting the documentation to single-file form!!!

So, I ended up using grep to scan the sphinx source code for expressions like single, single file etc. I soon hit singlehtml! Fortunately, there is a builder, named singlehtml, that produces a single HTML document for documentation that is split into multiple files. Hooray!!

I used the sphinx-build utility directly to generate a single HTML document containing the entire documentation. After changing to the documentation’s root directory, I issued the command:

sphinx-build -b singlehtml . zzz

I finally had a single HTML file at zzz/index.html, which I sent to the printer and got some nice documentation in-print.

How to create a single file of Sphinx based documentation, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.