Setting Up a New Sphinx Documentation Framework
When having to write documentation for different formats, I always use the reStructuredText [1] (or reST) format. As this is something that happens quite often, it made sense to put some effort in automating the set up of a new documentation framework, a reusable set up script.
The standard documentation framework that I use consists of Sphinx [2], which takes care of converting source pages written in reST into several formats: For example HTML, but also PDF or something more exotic like ePub files. Note that Sphinx already comes with a setup script, sphinx-quickstart [3] - but this doesn't take care of deploying files.
In order to be able to create a reusable framework, I split the necessary files into three groups:
- The Sphinx configuration itself,
- version information, and
- a LaTeX formatting template.
The Sphinx configuration
This part consists of two different files; A generic Makefile [4] to build the different artifact types - as well as a Sphinx configuration file (conf.py [5]) containing basic information about the project, and plugin details. These files rarely change after having initialized the framework.
Version information
The version information (version, or build number) can change per release, and is therefore contained in a separate …