Writing qiBuild documentation

One of the strengths of the qiBuild framework is the documentation you are reading right now ;)

It is completely written using sphinx, so do not hesitate to create links between various sections.

Please submit documentation updates (if relevant) when you submit your patches.

Building the doc

First, install tox, then run:

$ tox -c python/tox.ini -e doc

Documenting CMake API

The qiBuild CMake API is automatically generated from the comments of the cmake files in cmake/qibuild

If you add a new file, please add it to the list in ref/cmake/api.rst and in tools/gen_cmake_doc.py

(The script is called by tox right before building the sphinx documentation)

Also, when changing the comments of a cmake functions, please regenerate the .rst files to check the output.

Generating command line help

The output of

qibuild --help

or

qibuild make --help

is automatically generated using:

• The help argument used in the various _parsers functions.
• The first line of the docstring of module corresponding to the action.

So just make sure to write proper docstrings, and to correctly specify the help arguments when you configure your parser.

If you think the new action is worth it, you can also patch the qibuild man pages.

If you add a new executable, please add the corresponding man page in ref/man.

This allows the qiBuild debian package to pass lintian checks.

Documenting configuration files syntax

Right now the syntax of the configuration files is not frozen yet. Just make sure to update the Configuration files syntax section.

If your changes are incompatible, make sure (and add tests for it!) that you can convert from the previous version automatically.

Writing Python documentation

We are using sphinx autodoc extension to generate the qiBuild Python documentation, so please make sure to use valid rst syntax inside your docstrings.

Sphinx’s markup is light enough to be used directly in the docstrings, but please keep the files readable!

As a rule of thumb, if you want to refer to other parts of the documentation, do it in the .rst file, and not directly in the .py file.

This is BAD:

class Foo:
   """ Does this and that

   .. warning:: A big warning

   Example::

     # A big example

     def tutu:
         foo = Foo()

   .. seealso:

      * :ref:`qibuild-foo-stuff`

   """

.. foo.rst

Foo
---

.. autoclass: Foo

This is OK:

class Foo:
   """ Does this and that

   .. warning:: A big warning


   """

.. foo.rst

Foo
---

.. autoclass: Foo

   Example::

     # A big example

     def tutu:
         foo = Foo()

   .. seealso:

      * :ref:`qibuild-foo-stuff`

Also, even if the Module Index page is generated automatically py Sphinx, do not forget to update the qiBuild Python packages documentation toctree.