Sphinx Documentation

View the Docs

For our documentation we use Sphinx-docs and lives in the ./docs directory.

If you are currently running the entire stack you should be able to see the documentation by visiting http://localhost:8000.

The documentation is configured to watch for changes and re-build the documentation. This allows developers the ability to preview their documentation changes as they make them.

If you would like to run the documentation without the entire stack running you can do so by running:

docker-compose up docs

Editing The Docs

Edits are done in restructured text (rst).

While editing, you can check the logs by running

$ ./corgi docs logs

or

$ ./corgi docs logs -f

If edits have been made to the Navigation and are not reflected, re-build the docker image:

$ ./corgi build <stack-name>
$ ./corgi start [stack-name]

Auto-generated docs

Additional documentation is automatically pulled from this README and added to the sphinx docs when the docs service is running and when corgi.readthedocs.io is deployed. Each level 2 header (##) becomes a separate page in the sphinx docs. Links, like README.md, are resolved to github links relative to the markdown file’s parent directory.

This documentation is stored in docs/auto and this directory should not be modified directly. It is saved as markdown and converted with the m2r2 sphinx extension (see conf.py for more information).

When the files are generated, they are numbered so that the glob result will match the order the headers occurred in within the README.

The docs docker image uses watchdog to automatically update the auto-generated documentation as you update README.md.

There is a pre_build step in .readthedocs.yaml that generates the documentation during deployment.