News & Articles:

Sphinx not for Docs

We are fans of Sphinx – the Python Documentation Generator.

Originally developed for documenting software projects (and very good indeed for that), with a few tweaks it can become an excellent document preparation system. Want the same document as web pages and a well formatted PDF? Sphinx is the thing you need. ┬áThere are a few tweaks needed to the default Sphinx set-up to remove its heritage as a documentation system (the very word “documentation” is buried in many places). Lots of people have done this, but we couldn’t find instructions written down. So here goes. We’re assuming you know how to set Sphinx up for a doccy project (or that you’re capable of reading their docs on the subject).

  • Set up Sphinx for your project as you like. But, seriously, remember you want a Makefile.
  • Edit your main index file (usually index.rst in the same directory as the Makefile, and edit the “Welcome to …” line.
  • Edit conf.py and change every occurrence (there are three) of “Documentation” to something appropriate.
  • The last one is well hidden. The title at the top of the HTML version contains “documentation” as a default. Edit conf.py again, find and edit html_title ┬áto what you want.
  • It’s not strictly needed, but while in conf.py, consider edits to html_logo and latex_logo for some local branding.

All done. Simples!