Sphinx Guide¶
Sphinx serves as the primary backend for documentation generation. The sphinx-quickstart command initiates this process by creating the initial directory structure.
quickstart¶
[ ]:
$ mkdir docs
$ cd docs
$ sphinx-quickstart
Welcome to the Sphinx 5.3.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: DunderLab - Docs
> Author name(s): Yeison Cardona
> Project release []:
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:
Creating file docs/source/conf.py.
Creating file docs/source/index.rst.
Creating file docs/Makefile.
Creating file docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
make¶
To streamline the documentation process, consider adding a custom command in the Makefile. This command updates modules from the source code, as shown below. This addition simplifies the process of keeping your documentation synchronized with the latest code changes.
Then the documentation can be entirely updated and compiled with the command:
$ make clean buildapi html