Documentation¶

The sdr documentation is generated with Sphinx and the Sphinx Immaterial theme.

Install¶

The documentation dependencies are stored in docs/requirements.txt.

sphinx < 7.3
sphinx-immaterial == 0.11.8
# For some reason, if the below versions aren't specified, the dependency resolution takes 18 minutes in CI.
myst-parser == 0.18.1
sphinx-design  == 0.5.0
sphinx-last-updated-by-git == 0.3.6
sphinx-math-dollar == 1.2.1
ipykernel == 6.26.0
myst-nb == 0.17.2
pickleshare == 0.7.5  # Needed by ipykernel

Install the documentation dependencies by passing the -r switch to pip install.

$ python3 -m pip install -r docs/requirements.txt

Build the docs¶

The documentation is built by running the sphinx-build command.

$ sphinx-build -b dirhtml -v docs/ docs/build/

The HTML output is located in docs/build/. The home page is docs/build/index.html.

Serve the docs¶

Since the site is built to use directories (*/getting-started/ not */getting-started.html), it is necessary to serve the webpages locally with a webserver. This is easily done using the built-in Python http module.

$ python3 -m http.server 8080 -d docs/build/

The documentation is accessible from a web browser at http://localhost:8080/.