Building Documentation

The buildtest documentation is written in reStructuredText using sphinx. You should be familiar with rst if you want to contribute to user documentation.

ReadTheDocs

buildtest documentation is hosted by ReadTheDocs at https://readthedocs.org which is a documentation platform for building and hosting your docs.

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 (shahzebmsiddiqui@gmail.com) to grant access to this project.

Setup

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.

Running make html will build the sphinx project and generate all the html files in docs/_build/html. Once this process is complete you can view the html pages by running the following:

open _build/html/index.html

Please refer to the Makefile to see list of tags or run make for additional help.

Sphinx

The documentation is built via Sphinx using reStructuredText (rST) as its markup language. When you run make you are running sphinx-build command which will generate the documentation.

Sphinx will read the configuration file conf.py used for building the project. We have enabled a couple sphinx extensions in our project to customize our documentation

API Generation

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.

DocStrings

We have enabled napolean extension to support Google style docstring. Please follow this format when you are writting docstring for buildtest codebase. For more details on google style see: https://google.github.io/styleguide/pyguide.html