Documentation Generator

Requirements

The selected documentation tool is Sphinx.

If strictly required, developer documentation may be generated from source code using Doxygen.

If required for dissemination purposes, file conversion into common open and proprietary formats can be accomplished with Pandoc.

ReadTheDocs (either through the online service or using a local deployment) can be used for automated documentation generation using Sphinx and reStructuredText documentation stored in a Git repository.

Rationale

The main objective is to find a tool adequate for user documentation, that:

  • Is easy to work with, by non-technical writers
  • Can support the translation process (from EN to PT, CY, BG, etc.)
  • Can generate outputs in different formats (HTML, PDF)
  • Can produce print quality documents, using different stylesheets
  • Can also support the creation of developer documentation from source code (e.g. API documentation).

All documentation must be kept under version control: differences or changes between versions must be readily identifiable. (For example, if the English version of a user manual is updated, changes are required in the localised versions, in the specific files, paragraphs or lines that changed).

Fast identification of changes and differences is a built-in feature of the version control system if the documentation is stored in plain text files. This excludes the use of binary formats, such as Microsoft Word documents (DOC), or zipped XML formats, such as ISO/IEC 26300:2006 OpenDocument (ODT) or Microsoft Office Open XML (DOCX). (Conversion tools from and to these formats must nevertheless be available).

By using plain text files, the documentation content can be produced using a simple text editor (i.e. does not require dedicated tools such as word processors or desktop publishing tools). However, a long or steep learning curve should be avoided, which excludes markup languages such as DocBook or LaTeX, that are overly complex.

A lightweight markup language (such as Markdown, reStructuredText or Wiki Markup) is thus required: “simple syntax, designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form”.

Other basic feature requirements are:

  • separation of content (structured text) and presentation (formatting styles),
  • support for style sheet languages such as Cascading Style Sheets (CSS) and/or the Extensible Stylesheet Language (XSL),
  • support for HTML/XML templating engines in the automated documentation build processes, and LaTeX templates for printed documentation (as a common intermediate step for generating print-quality PDF output).

Analysis of alternatives

The following table contains a comparison of 5 documentation generators:

Comparison of documentation generator tools

Evaluation:

  • Support for specific programming languages – i.e technical documentation automatically generated from source code – is shown in the results table above.
  • For mere syntax highlighting, Sphinx uses the Pygments library (under BSD licence) that supports all the listed programming languages.
  • ROBODoc was excluded on the basis of licence compatibility.
  • ROBOdoc and Javadoc are not under active development – see ohloh.
  • Javadoc is typically used for Java code documentation and is not not really a general purpose documentation generator.
  • ApiGen and Javadoc are dominated alternatives when compared to Doxygen and Sphinx.

Real-world use

Basic information on developer community activity is available through the following Ohloh indicators on documentation tools.

Since the only non-dominated alternatives are Doxygen and Sphinx, software adoption and real-world use cases were only investigated for these products.

Extensive lists of projects using Doxygen and projects using Sphinx are available online.

The following conclusions can be drawn:

  • Doxygen is mainly used for developer documentation, such as API documentation, although some open-source projects also use it for user documentation (PostgreSQL, PostGIS, GEOS, GDAL).
  • Sphinx is extensively used for user manuals, tutorials and books, but can also be used for developer documentation, either through direct support or through additional ‘language domains’, such as javasphinx.
  • Doxygen output can be incorporated in Sphinx documentation, via the BREATHE extension (under BSD licence).

The following links illustrate the use of Sphinx for different (technical) purposes:

Conclusions

  • Sphinx is better for user documentation.
  • The PANDOC library (under GPLv2 licence) can be used to convert RST to a large number of formats (including DOCX and ODT).
  • The javasphinx extension to the Sphinx documentation system adds support for documenting Java projects. It includes a Java domain for writing documentation manually and a javasphinx-apidoc utility which will automatically generate API documentation from existing Javadoc markup.
  • Doxygen can complement Sphinx (for developer documentation and programming language not supported by Sphinx).
  • ReadTheDocs.org is an online hosting service for Sphinx documentation. The service can be connected to a repository under version control, using either Bazaar, Git, Mercurial or Subversion. Web hooks are supported (when changes are committed, the documentation is automatically rebuilt), also with two online repository hosting services, GitHub and BitBucket. The ReadTheDocs software is available under an MIT licence and a local deployment can be used (if required).

Footnotes

[1]An overview and list of bookmarks which is itself written in reStructuredText, build in Sphinx, stored on a BitBucket repository under Mercurial version control and published online using ReadTheDocs.org.