Sphinx autodoc Docker example

This repo can be used as a template for a Python project with Sphinx documentation.

Installing Docker Desktop

This project was tested using Docker Desktop on Windows 11 with a WSL2 engine. See https://docs.docker.com/desktop/windows/wsl/.

Available services

• bash -- Use docker compose run --rm bash to launch a bash shell or docker 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 using doc-clean and doc-build. The webserver can also be launched by running the doc-serve script in a bash 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.

Installing dependencies

The Docker images generated by this project will run pip install -r /requirements.txt during the build.

Enabled Sphinx extensions

autodoc

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.

Intersphinx — Linking to external documentation

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.

MathJax — LaTeX support

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.