The buildtest documentation is written in reStructuredText using sphinx. You should be familiar with rst if you want to contribute to user documentation.
buildtest project can be found at https://readthedocs.org/projects/buildtest/
which will show the recent builds and project setting. If you are interested
in becoming a maintainer, please contact Shahzeb Siddiqui (
to grant access to this project.
buildtest documentation is located in top-level docs directory.
If you want to build the documentation you will need to make sure your python environment
has all the packages defined in
docs/requirements.txt. If your environment
is already setup as described in Installing buildtest then you can skip this step.
To install your python packages, you can run the following:
pip install -r docs/requirements.txt
Building docs locally¶
To build your documentation, navigate to the docs directory and run the following:
cd docs make clean make html
It is best practice to run
make clean to ensure sphinx will remove old html
content from previous builds, but it is ok to skip this step if you are
making minor changes.
make html will build the sphinx project and generate all the html
docs/_build/html. Once this process is complete you can view the html
pages by running the following:
Please refer to the
Makefile to see list of tags or run
make for additional help.
We make use of Sphinx AutoAPI to generate buildtest API documentation that is hosted on https://buildtest.readthedocs.io/en/devel/api/index.html. The Sphinx AutoAPI configuration is configured in sphinx configuration file conf.py. For more details on configuration options see https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
Command Line Documentation¶
We make use of sphinx-argparse to generate documentation for buildtest command line that is hosted at https://buildtest.readthedocs.io/en/devel/command.html. In order to use this tool one must install this package and enable the extension in sphinx configuration.