How to Edit This Document¶
This documentation is a sphinx project. From this section, you will get set on how to build, install, edit and view documentation locally on your development environment.
The documentation files are located in the
How to Install & Build Locally¶
Navigate to http://localhost:8002/ to view the docs, once your local server is up.
local.yml has the volume mappings
./docs/_build/html:/app/docs/_build/html, changes made to files
during development should be reflected in the running
as soon as the dev server process restarts. The
compile_docs container has a
restart: always configuration to allow the docs application to automatically
compile the markdown and reStructuredText files in the project into
then, sync these files.
So when you do a change in the docs, instead of restarting all services, or if you’re running them in daemon mode, when you reload the documentation page, your changes will reflect.
Running the tests¶
tests/test_docker.sh shows you how to run the tests for the documentation
$ docker-compose -f local.yml run documentation make -C /app/docs doctest
How to Update Table of Contents¶
The table of contents can be updated using
To add a new table of contents section to the current one, the file(s) with the
section’s content have to be linked using sphinx from the entry-point file of
the project i.e.
In the current
index.rst, it includes a root
toctree directive, under which
we can add content files or create new
toctree sections for the table of
... .. toctree:: :maxdepth: 4 #indicate maximum depth of your tree :caption: Descriptive caption top-level-file-1 top-level-file-2 ... ...
top-level-file-2 can be markdown or reST files
top-level-file-2.rst in the local
This will render like this on the table of contents:
You can read more about toctree here