Documentation in the modern age · Cool kids used to do Doxygen Doxygen in a nutshell: Doxygen is...
13
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
Transcript of Documentation in the modern age · Cool kids used to do Doxygen Doxygen in a nutshell: Doxygen is...
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 advancedusers.
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 seemsto be relevant – although the pages themselves have not beenupdated 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 onreadthedocs.org, with a better search tool than offlinedocumentation.
Main features of Sphinx:Supports a variety of output formats, including HTML and PDF.Easy cross-referencing via semantic markup and automatic links forfunctions, classes, citations.Simple hierarchical structure of the documentation tree withautomatic 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) forgenerating 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 bymeans of include dependency graphs, inheritance diagrams, andcollaboration 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 andproduces Sphinx documentation.
Breathe can be integrated with readthedocs to post documentationonline.
Support for hybrid syntax, i.e., using reStructuredText in Doxygenmarkup.
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 aredesigned to simplify your life in maintaining a coherent documentation.For projects written in Python/Julia, I recommend learning Markdown andSphinx. For C++, Doxygen is still the most popular tool.But:
How do you encourage users to readdocumentation?
See also: https://en.wikipedia.org/wiki/Comparison_of_documentation_generators
13/13 Giacomo Nannicini – Documentation in the modern age © 2018 IBM Corporation
