Documentation

These docs were generated with Sphinx: https://www.sphinx-doc.org/

Requirements

A recent version of sphinx (at least version 1.3) is required. The easiest way to install this version is:

pip install --upgrade Sphinx

We use automatically-generated “doxyen” for C++ code-level documentation and reStructuredText (rst, the standard for Python documentation) for high-level and Python documentation. You can click the link “Show Source”, on this page’s side panel, to see what reStructuredText looks like.

reStructuredText (rst)

reStructuredText is the tool of choice for writing overview documentation (and a good way to generate quick web pages). See Links below for source documentation. Sphinx is a documentation toolkit built on top of restructured text, used for Python’s standard documentation.

Projects that contain a DOCS_DIR in their CMakeList.txt’s i3_project invocation will have documentation generated from the .rst source in that directory when make html or make docs is run. For an example see the documentation for project Dataio. See also Project Directory Structure and Targets.

For project P, the built html documentation will be found in $I3_BUILD/docs/projects/P.

Doxygen

Doxygen is a open-source application which generates good-looking documentation of C, C++, Java and Python, from the source code itself. One particularly appealing apspect of doxygen is its ability to cross-reference classes and functions and generate inheritance and collaboration diagrams. Try them out.

On the other hand, doxygen isn’t very good for hand-written explanatory, high-level documentation.

There is an excellent introduction on how to document the code located at https://doxygen.nl/manual/docblocks.html

For a full description of what one can do with doxygen consult the Doxygen homepage , in particular the users manual.

By default doxygen is configured to search the public/ and resources/docs/ directories of your project looking for files ending in the patterns .h, .dox, .cxx, .cpp, .C, and .cc. The docs generated by putting doxygen-parsed comments around your classes and methods generally give a good idea of what a specific class does but, typically do not do a good job of explaining how the classes fit together or how the project as a whole is to be used. For this use reStructuredText.

Linking to doxygen docs from reStructuredText

To provide a link over to the autogenerated doxygen documentation from the rst docs, for project P, the path will be ../../doxygen/P/index.html. e.g. for project dataio, the rst source will look like:

See the `doxygen <../../doxygen/dataio/index.html>`_ docs.

Building the documentation

Simply execute make docs in your project or the workspace. See also Targets.