Documentation

Both the end-user and developer documentation is combined into a single sphinx build (the two were previously split between github pages and sphinx).

Building

To build the documentation, simply run tox -e docs in the project root. Serving the docs through http can be achieved by subsequently running (cd docs/_build/html; python -m SimpleHTTPServer 8080) and accessing them on http://localhost:8080/.

READMEs

Many of the folders in the project have a README.rst which describes the purpose of the contents in that folder. These files are automatically included when building the documentation, through use of the include directive.

Include files for the providers and plugins are autogenerated through the sphinx conf.py script.

Links

All links in rst files outside of docs/ (but also docs/README.rst) that link to other rst files are relative and reference folder names when the link would point at a README.rst otherwise. This is done to take advantage of the github feature where README files are displayed when viewing its parent folder. When accessing the manifests/ folder for example, the documentation for how manifests work is displayed at the bottom.

When sphinx generates the documentation, these relative links are automatically converted into relative links that work inside the generated html pages instead. If you are interested in how this works, take a look at the link transformation module in docs/transform_github_links.