IBM T.J. Watson

Documentation in the modern age

Giacomo Nannicini

October 16, 2018.

1/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Overview

Main types of documentation:

1 User documentation (getting started, FAQ, common tasks...).

2 Code documentation (i.e., comments).

3 API documentation.

All three are important:

1 Important for non-advanced users.

2 Important for code maintenance/development.

3 Important for code maintenance/development, and for advanced users.

2/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation User documentation

Guidelines: There are no specific guidelines, anything works! User manual (PDF, HTML or Markdown), online FAQ, ...

In COIN-OR Optimization Suite: Many projects have an HTML user manual (Clp, Cbc, Ipopt, Bonmin, Couenne, ...), sometimes a PDF. The wiki pages contain a summary that for the large part still seems to be relevant – although the pages themselves have not been updated in a long time.

3/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation API documentation: the gold standard

4/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation API documentation: the gold standard

5/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Cool kids do Sphinx

Sphinx in a nutshell: Documentation tool originally created for the Python documentation. Uses reStructuredText. Released under BSD. Seamless (well – almost) online hosting of the documentation on readthedocs.org, with a better search tool than offline documentation.

Main features of Sphinx: Supports a variety of output formats, including HTML and PDF. Easy cross-referencing via semantic markup and automatic links for functions, classes, citations. Simple hierarchical structure of the documentation tree with automatic links to siblings, parents, chidlren. Automatic indices. Extensible. Easy configuration, mostly automatic.

6/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Example of Sphinx: NumPy

7/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Example of Sphinx: the Python documentation

8/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Sphinx: markup language

Docstrings in NumPy format:

9/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Cool kids used to do Doxygen

Doxygen in a nutshell: Doxygen is the de facto standard tool (according to its website) for generating documentation from annotated C++ sources. Reads from source files – which is not as easy as in Python.

Main features of Doxygen: Supports a variety of output formats, including HTML and PDF. It can extract the code structure from undocumented source files. It can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams.

10/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Example of Doxygen: Cbc

11/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation Doxygen versus Sphinx

Very rough comparison: Sphinx produces “prettier” output and has more extensions. Doxygen is more powerful in parsing complex (i.e., badly written) code and still making sense of it. Sphinx essentially supports only a few different syntaxes. Sphinx has easier configuration.

They can work together: The Sphinx module Breathe parses Doxygen XML output and produces Sphinx documentation. Breathe can be integrated with readthedocs to post documentation online. Support for hybrid syntax, i.e., using reStructuredText in Doxygen markup.

12/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation The most glaring issue regarding documentation

There are many different tools for API documentation. Most of them are designed to simplify your life in maintaining a coherent documentation. For projects written in Python/Julia, I recommend learning Markdown and Sphinx. For C++, Doxygen is still the most popular tool. But: How do you encourage users to read documentation?

See also: https://en.wikipedia.org/wiki/Comparison_of_ documentation_generators

13/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation