Was this page helpful?
CommandsCopy
Use the command-line interface to run the following commands.
Note
Make sure you meet the necessary prerequisites before running these commands. For details, see Prerequisites.
Setup commandsCopy
setupenvCopy
Installs system dependencies required to build the docs, such as Poetry.
make setupenv
setupCopy
Installs the required Python dependencies to build the documentation.
make setup
Note
make setup
is called automatically before running build commands.
updateCopy
Updates Python dependencies to the latest version.
make update
As a result, updates the poetry.lock
file.
Build commandsCopy
previewCopy
Builds a local instance of the docs site so you can view the rendering in a sandbox environment on your local browser.
To preview the docs:
Build the docs.
cd docs make preview
Open http://127.0.0.1:5500/ with your preferred browser.
Tip
You can pass custom options to increase or decrease verbosity. For a list with all the available options, refer to the Sphinx documentation.
To increase verbosity, use the option -v
:
make preview SPHINXOPTS=-v
To decrease verbosity, use the option -Q
:
make preview SPHINXOPTS=-Q
TroubleshootingCopy
Issue: pyproject.toml changed significantly since poetry.lock was last generatedCopy
Solution:
Run the following command:
poetry lock --no-update
Run the make preview command again.
Issue: Keyring asks for a passwordCopy
This issue is due to a known problem with Poetry that primarily affects GNOME users. For more details, see poetry/poetry#8761.
Solution:
Edit docs/Makefile to add the POETRY variable as follows:
POETRY = PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring poetry
Run the make preview command again.
multiversionpreviewCopy
Generates a local instance of the docs site with all specified versions available for navigation. You can view the rendering in a sandbox environment on your local browser.
To preview multiple versions:
Build the docs.
cd docs make multiversionpreview
Open http://0.0.0.0:5500/ with your preferred browser.
For further guidance on using the multiversionpreview command
, see Multiversion configuration.
dirhtmlCopy
Generates the documentation in HTML format.
Note
The command make dirhtml
is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run make dirhtml
, but make preview
instead.
cd docs
make multiversion
Docs are generated under the docs/_build/dirhtml
directory.
multiversionCopy
Generates multiple versions of the docs with all specified versions available for navigation.
Note
The command make multiversion
is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run make multiversion
, but make preview
instead.
cd docs
make multiversion
Docs are generated under the docs/_build/dirhtml
directory.
redirectsCopy
Generates HTML redirects from the _utils/redirects.yaml
file.
Note
The command make multiversion
is aimed to be used by GitHub Actions CI.
cd docs
make multiversion
Redirects are generated under the docs/_build/dirhtml
directory.
Clean commandsCopy
cleanCopy
Before making changes to the docs, it’s helpful to clear the previous build by deleting the contents of the build
directory.
This ensures that the changes you make are reflected correctly.
cd docs
make clean
Test commandsCopy
linkcheckCopy
Checks the documentation site for broken links.
cd docs
make dirhtml
make linkcheck