| orphan: |
|---|
Both the end-user and developer documentation is combined into a single sphinx build (the two were previously split between github pages and sphinx).
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/.
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.
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.