Contributing to the documentation

Documentation is super important and making sure we have straightforward, up to date documentation is a crucial part of making sure this project is as reproducible as possible.

This project has been put together by a number of different collaborators so there may be bits of the code you find documented well and sections in need of improvement. We’re aware of this and are trying our best to improve the documentation. But you can help!

Before starting on this page make sure you’ve read our get ready to contribute guide.

About RAMP-UA Documentation

Documentation for this package is generated using Sphinx and is written in reStructured text.

Documentation is found in two primary places: documentation pages like this written by hand in docs/source and docstrings that are found within code functions and classes. Docstrings aim to provide a specific overview of the behaviour of the code component it is within whilst documentation pages are more general guides for the project as a whole.

Building documentation locally

You can build and test documentation as you contribute to it using the following instructions when you are within the ramp-ua conda environment. To generate the specific API reference documentation from docstrings we use the sphinx.ext.autodoc extension which automatically extracts docstrings and renders them in the documentation pages. Using this extension is specified within the docs/source/conf.py file so that sphinx knows to use it.

To build the documentation locally:

$ cd docs/

# remove any previous rendered documentation
$ make clean

# create new html documentation
$ make html

If a new module is added you will need to create new .rst files using the sphinx-apidoc command.

$ cd docs/

$ sphinx-apidoc -f -o source/ ../new_module/

This will generate new .rst files from the new modules docstrings that can then be rendered into html by running make html.