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.
On linux, simply install sphinx, and then run
$ cd doc
$ make
Note: on archlinux, (or any distribution using python3 by default), because we use a custom sphinx extension written in python2, you have to install python2-sphinx and use:
$ cd doc
$ make SPHINXBUILD=sphinx-build2
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_rst.py
Also, when changing the comments of a cmake functions, please regenerate the .rst files to check the output.
You can do so by running make in doc/, or using:
$ cd doc
$ python tools/gen_cmake_rst.py ..
The output of
qibuild --help
or
qibuild make --help
is automatically generated using:
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.
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.
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.