Documentation

This page describes provides an overview of the IceTray documentation system. Because of IceTray’s modular design, and the fact that documentation is provided from number of different sources, it can be quite complicated. The is system uses sphinx to translate these different sources into html. sphinx was originally developed to be the documentation system for python, but has developed support for many languages. There are four main sources for documentation:

• restructured text (rst) – for writing high level descriptions of the code

• sphinx python – automatically documents python code based on the code and provided comments

• doxygen – parses c and c++ code and automatically produces documentation and creates documentation based on the code and provided comments

• icetray-inspect – analyses IceTray interfaces such as IceTray modules, service factories and tableio readers.

sphinx then combines these into a single group of html files. Cross references are possible between each of these groups of sources.

Building the docs

Building the entire docs can take quite some time, so they are available at https://docs.icecube.aq/ where they are regularly updated. However, it is often necessary to build the docs yourself. The docs are build with a python script called docs-build which will be available in your path if you are in an IceTray environment. If run without any arguments the entire document will be built which will take some time. Usually when writing documentation you will only want to see the docs for one or two projects. This can be accomplished with:

$ ./env-shell.sh docs-build --projects astro bayesian-priors --open

This will only build two projects: astro and baysian-priors. In addition, the --open option will open the html file for you in the browser as soon as the build is complete. Other wise you will have to find the docs yourself in the directory they are written to $I3_BUILD/docs/build/html/.

Another useful option is the -j option which will specify how many parallel process to run. This is analogous to the -j option passed to make. For example if your machine has eight processors you should run docs-build -j8 to run with eight concurrent processes.

Other steps to speed up the build are to skip the sources you are not currently interested: --no-general-docs will skip the documents which are not associated with any project such as the “Basic Info” and “Of General Interest” sections of the main page. --no-project-docs will skip the build of project documents found in each projects resources/docs, --no-python will skip building the python docs, --no-doxygen will prevent reading c/c++ docs with doxygen, --no-cpp will skip reading the docs generated by doxygen into the documentation and --no-inspect will skip examining the IceTray modules to document their interfaces. For a complete list of options available run docs-build --help.

Writing Documentation

Project Docs

Each project in $I3_SRC should contain a docs directory which will contain the primary documentation for that project. These docs should serve an an overview for the project and other information not directly linked to specific pieces of code. This documentation is written in a format called ReStructuredText or (rst) which is a fairly easy format to learn. An introduction to rst can be found at https://docutils.sourceforge.io/rst.html.

Many editors also have support for rst: emacs support can be found at https://docutils.sourceforge.io/docs/user/emacs.html. vim has support with riv.

References to Autodocs

Sphinx comes with an internal linking system as well as a sophisticated cross reference system. Before attempting to write documentation you should familiarize yourself with this syntax. This section will summarize the basics for cross referencing the the automatically generated.

To cross reference another project’s rst documentation. You can reference a project’s documentation by filename with :doc:`/projects/myproject/index. If the project’s documentation contains a label in its index.rst file such as .. _myproject: then you can also reference it with :ref:`myproject`.

To cross reference the python API reference use sphinx’s python domain: :py:mod:`icecube.myproject` for the entire module, :py:class:`icecube.mpyroject.myclass` for classes, :py:func:`icecube.myproject.myfunction` for python functions, and so on and so forth. The full list of available directives is available at Sphinx’s documentation for the-python-domain.

To cross reference the C++ documentation provided by breathe can be done either by path with :doc:`/doxygen/myproject/index` or by label :ref:`myproject-cpp`. Individual classes and struct can be referenced with :cpp:class:`MyClass` and functions with :cpp:func:`MyFunction`. See the complete list of available directives on Sphinx’s documentation for The C++ Domain.

To reference the automatically generated icetray-inspect docs must be done by path with :doc:`/inspect/myproject`. Individual modules and service factories are referenced by abusing the javascript domain :js:data:`MyModule`.

Note

All of the above examples can be used with a different name for the link. For example :doc:`/projects/myproject/index can be replaced with :doc:`This is a link to myproject </projects/myproject/index> or :ref:`myproject-cpp` can be replaced with :ref:`This is a link to the C++ docs <myproject-cpp>`.

The cross references by path can also be used in toctrees:

.. toctree::
   :maxdepth: 1

   /python/icecube.myproject
   /doxygen/myproject/index
   /inspect/myproject

Or if you don’t like using the titles of the page as the link provide your own:

.. toctree::
   :maxdepth: 1

   Python API Reference </python/icecube.myproject>
   C++ API Reference </doxygen/myproject/index>
   IceTray Inspect Reference </inspect/myproject>

FAQs About Building the Documentation

Q:

While building the docs I see errors like

:44: (ERROR/3) Unknown interpreted text role "cpp:class".

A:

You’ll generally see errors like this during the two icetray-inspect phases of the documentation build. They refer to text roles that are compatible with sphinx, but not understood by docutils (which underpins icetray-inspect). These errors are harmless. Unfortunately there’s nothing we can do to suppress or modify them, as they are printed straight to stderr from deep within docutils.

Q:

I want to help fix the docs, but when building I get an opaque wall of text! HELP!

A:

docs-build and icetray-inspect both understand rich-text formatting as implemented by the rich python library. All you need to do is install it. The easiest way is via pip3.

$ pip3 install rich

The next time you run docs-build you’ll get organized and colorized output.