https://github.com/yinchi/sphinx-autodoc-example
Sphinx autodoc example using Docker
https://github.com/yinchi/sphinx-autodoc-example
docker python sphinx-autoapi sphinx-autodoc
Last synced: 9 months ago
JSON representation
Sphinx autodoc example using Docker
- Host: GitHub
- URL: https://github.com/yinchi/sphinx-autodoc-example
- Owner: yinchi
- Created: 2023-04-03T21:06:59.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-03T21:07:02.000Z (about 3 years ago)
- Last Synced: 2025-04-01T14:49:35.175Z (about 1 year ago)
- Topics: docker, python, sphinx-autoapi, sphinx-autodoc
- Language: Python
- Homepage:
- Size: 4.88 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Sphinx autodoc Docker example
This repo can be used as a template for a Python project with [Sphinx](https://www.sphinx-doc.org/) documentation.
## Installing Docker Desktop
This project was tested using Docker Desktop on Windows 11 with a WSL2 engine. See .
## Available services
- **bash** -- Use `docker compose run --rm bash` to launch a `bash` shell or `docker compose run --rm bash ` 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.