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:
name – The name of the project.
version – The version of the project.
description – The summary description of the project.
One of authors/maintainers.
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.