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 text file (VERSION [6]). Its values will be read and included by the build process.
LaTeX template
Thirdly, the LaTeX formatting template latex-styling.tex [7] contains styling information that will be used when building PDF files, and is also stored in a separate file. This allows for easy updating and different re-use across projects.
Setting up the framework
The reusable framework consists of a collection of the files mentioned above, as well as some basic static files.
So all that's left when setting up a new documentation framework is creating some directories, copying the files, and... that's basically it.
In order to take care of this, I wrote a simple Bash installer script, installer.sh [6]. A new feature in Bash version 4 is the support of associative arrays. That functionality makes it easier to write a generic, reusable script which takes care of creating and copying files and directories.
A simple
./installer.sh TARGET
will set up the framework in the directory
TARGET
. Of course the
prerequisites (Sphinx and GNU Make) need to be installed as well. If they are,
all that's left to do is write some content in reStructuredText [1], and let
Sphinx [2] build it into an artifact of your choosing, for example HTML:
make html
The reusable Sphinx framework can be found at https://github.com/PeterMosmans/setup-sphinx-framework
| [1] | (1, 2) http://docutils.sourceforge.net/rst.html |
| [2] | (1, 2) http://www.sphinx-doc.org |
| [3] | http://www.sphinx-doc.org/en/master/man/sphinx-quickstart.html |
| [4] | https://github.com/PeterMosmans/setup-sphinx-framework/blob/master/Makefile |
| [5] | https://github.com/PeterMosmans/setup-sphinx-framework/blob/master/conf.py |
| [6] | (1, 2) https://github.com/PeterMosmans/setup-sphinx-framework/blob/master/installer.sh |
| [7] | https://github.com/PeterMosmans/setup-sphinx-framework/blob/master/latex-styling.tex |
Comments
comments powered by Disqus