This repo can be used as a template for a Python project with Sphinx documentation.
This project was tested using Docker Desktop on Windows 11 with a WSL2 engine. See https://docs.docker.com/desktop/windows/wsl/.
- bash -- Use
docker compose run --rm bash
to launch abash
shell ordocker compose run --rm bash <cmd>
to run a single command. - sphinx -- Use
docker compose up sphinx -d
to launch a simple webserver to serve project's documentation. This also regenerates the documentation from scratch usingdoc-clean
anddoc-build
. The webserver can also be launched by running thedoc-serve
script in abash
shell.
Both services will mount the project's app
directory as /app
within the Docker container, allowing changes in the host machine to be reflected in the Docker containers and vice versa.
Note that Sphinx will not automatically update to reflect changes to project code in app
. However, doc-clean
and doc-build
can be run in bash
without shutting down a running Sphinx service.
The Docker images generated by this project will run pip install -r /requirements.txt
during the build.
This project generates ReStructuredText documentation from Python docstrings using autodoc
. The generated .rst
files are in docs/source/apidoc
. The files are generated automatically by doc-build
and doc-clean
will remove them.
This project uses the sphinx.ext.intersphinx
extension to link to external Sphinx documentation. Setup for Intersphinx is performed using the intersphinx_mapping
variable in app/docs/source/conf.py
.
The sphinx.ext.mathjax
extension is enabled to allow for LaTeX markup in the documentation. Disable this in app/docs/source/conf.py
if not needed.