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. The file .readthedocs.yaml is a special configuration file used to configure the build process for ReadTheDocs. Please refer to this file to tweak changes to ReadTheDocs.
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 setup, then you can skip this step.
To install python dependencies for documentation build, you can run the following:
# install from requirements file pip install -r docs/requirements.txt # install from pyproject.toml pip install '.[docs]'
Building docs locally
To build your documentation, navigate to the docs directory and run the following:
cd docs make clean make html
It’s 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.
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
Generating Documentation Examples for Buildtest Tutorial
The documentation examples for the buildtest tutorial are run inside the container image ghcr.io/buildtesters/buildtest_spack:latest which means that some of the example output needs to be generated manually. There is a script doc-examples.py that is responsible for auto-generating the documentation examples inside the container.
To get into the container along with the buildtest codebase you will need to run the following commands
You may need to source /etc/profile in your container if you see module command is not found.
You will need to volume mount $BUILDTEST_ROOT into /home/spack/buildtest in-order to get buildtest code-base accessible inside the container.
docker run -it -v $BUILDTEST_ROOT:/home/spack/buildtest ghcr.io/buildtesters/buildtest_spack:latest
Once you are in the container run the following commands
cd /home/spack/buildtest source scripts/spack_container/setup.sh
Once your setup is complete, you can auto-generate documentation examples by running the following:
Alternatively, the script can also be invoked via python as shown below:
Please verify all the auto-generated examples that will be used in the documentation. Once you are content with all the changes please add all
the changes via