Documentation and ReadTheDocs Setup

Using the Documentation Locally

Note

This tutorial assumes, that the project is already installed via poetry!

  • To build the documentation run the following command from the qunicorn root directory:

poetry run invoke doc

  • To view the generated documentation open docs/_build/index.html in your browser or use the following command to open the browser:

poetry run invoke browse-doc

  • To update the source code documentation under docs/source run

poetry run invoke update-source-doc

To search for valid reference targets use the following command after building the documentation at least once:

poetry run invoke doc-index -f <insert search string here>

See also

The documentation is built using Sphinx and reStructuredText.

Documentation for the reStructuredText syntax and available roles/directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

Hint

Markdown files are also supported:

Markdown uses the MyST syntax: https://myst-parser.readthedocs.io/en/latest/syntax/typography.html

Hint

Some documentation parameters are configured in the pyproject.toml file.

Updating Requirements

If the requirements of the main project have changed, run the following command to update the requirements across the whole project (includding the documentation).

poetry run invoke update-dependencies

Setting up remote

Initial Setup

  • Register at: ReadTheDocs

  • Import a Project from GitHub

  • Choose Branch

  • Build the Docs

Testing

  • Push changes to Github

  • Rebuild Docs

Setting Up Webhook