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
If you add a new file, please add it to the list in
ref/cmake/api.rst and in
(The script is called by tox right before building the sphinx documentation)
Also, when changing the comments of a cmake functions, please
.rst files to check the output.
Generating command line help¶
The output of
qibuild make --help
is automatically generated using:
helpargument 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
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
This allows the qiBuild debian package to pass
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¶
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
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`