Usage

The SphinxConfig class will load the configuration from pyproject.toml. By passing globalns=globals() to the class constructor, the keys parsed from the pyproject.toml file will be added to the global namespace of the conf.py file.

For example:

# conf.py

from sphinx_pyproject import SphinxConfig

config = SphinxConfig("../pyproject.toml", globalns=globals())

author  # This name *looks* to be undefined, but it isn't.

The SphinxConfig class also provides a collections.abc.Mapping interface. If you are going to override or modify one of the configuration values after parsing it, the recommended approach is to explicitly assign the name:

extensions = config["extensions"]
extensions.append("sphinx.ext.autodoc")

This will prevent warnings from linters etc., but is not necessary for Sphinx to see the configuration.

Note

At time of writing the “Poetry” tool does not support PEP 621. To enable a mode compatible with the [tool.poetry] table supply the argument style="poetry". For example:

config = SphinxConfig("../pyproject.toml", style="poetry")

Additionally the SphinxConfig class takes an optional parameter config_overrides that can be used to dynamically update values from pyproject.toml. This can be helpful for setting dynamic values like version.

# conf.py
from sphinx_pyproject import SphinxConfig

from myproject import __version__ as myproject_version

config = SphinxConfig("../pyproject.toml", globalns=globals(), config_overrides = {"version": myproject_version})

Configuration

sphinx-pyproject parses the configuration from the [project] and [tool.sphinx-pyproject] tables in pyproject.toml. The [project] table is defined in PEP 621. sphinx-pyproject only uses the following keys:

The remaining Sphinx configuration values can be provided in the [tool.sphinx-pyproject] table.

See this project’s pyproject.toml file for an example of this configuration.