When having to write documentation for different formats, I always use the reStructuredText  (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 , 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  - 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  to build the different artifact types - as well as a Sphinx configuration file (conf.py ) containing basic information about the project, and plugin details. These files rarely change after having initialized the framework.
Thirdly, the LaTeX formatting template latex-styling.tex  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, setup_sphinx_framework.sh . 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.
will set up the framework in the directory
. 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 , and let
Sphinx  build it into an artifact of your choosing, for example HTML:
The reusable Sphinx framework can be found at https://github.com/PeterMosmans/setup-sphinx-framework
|||(1, 2) http://docutils.sourceforge.net/rst.html|
|||(1, 2) http://www.sphinx-doc.org|
|||(1, 2) https://github.com/PeterMosmans/setup-sphinx-framework/blob/master/setup_sphinx_framework.sh|