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 codesphinx 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 andtableio
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 withsphinx
, but not understood bydocutils
(which underpinsicetray-inspect
). These errors are harmless. Unfortunately there’s nothing we can do to suppress or modify them, as they are printed straight tostderr
from deep withindocutils
.
- Q:
I want to help fix the docs, but when building I get an opaque wall of text! HELP!
- A:
docs-build
andicetray-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 viapip3
.$ pip3 install rich
The next time you run
docs-build
you’ll get organized and colorized output.