1.1. Contributing to Documentation

1.1.1. Forking the Repository

Go to this documentation’s GitHub repository and fork it (see GitHub’s documentation for details on forking if you do not know how to fork a repository).

Then clone your fork with git clone so you can work with the repository locally.

1.1.2. Make your Changes

Modify or complement the existing .rst-files to your liking.

Help with the most common ReStructuredText/Sphinx directives can be found here. For a more extensive documentation of the capabilities of Sphinx visit the official website.

1.1.3. Build the Docs locally

Since Sphinx follws the WYSIWYM paradigm, it is a good idea to build the html output, to check if your changes work out as expected.

Probably easiest way to do so is to setup a virtual environment for python by executing the following commmand inside your cloned fork of the documentation repository:

$ python3 -m venv venv

Activate the virtual environment with

$ source venv/bin/activate

and install the Sphinx dependencies by executing

$ pip3 install -r requirements.txt

Now you can build the documentation by running

$ make html

Note

Always make sure to have the virtual environment activated when executing the make html command.

1.1.4. View the HTML output

You can view the HTML output by opening _build/html/index.html with a webbrowser.

$ firefox _build/html/index.html & disown

1.1.5. Autogenerate Documentation

Attention

Autodoc is disabled for now. Either implement a docker workflow to build the docs where all runtime dependencies of the documented source code are met or just don’t use autodoc. We stick with the latter one for now.

To generate API documentation for Python packages add the them as submodule under the src directory.

$ PKG_NAME="insert-your-package-name-here" && \
git submodule add https://github.com/HippoCampusRobotics/$PKG_NAME.git src/$PKG_NAME

Add the package name to the packages list in conf.py.

Then add the package in src.rst. If you get errors/warning telling you that something related to your newly added package could not be imported, make sure you add all external modules imported in your package/modules to the autodoc_mock_imports list in conf.py.