Move some of your Sphinx configuration into pyproject.toml
| Docs |   |
| Tests |     |
| PyPI |     |
| Anaconda |   |
| Activity |    |
| QA |    |
| Other |    |
sphinx-pyproject can be installed from PyPI or Anaconda.
To install with pip:
$ python -m pip install sphinx-pyprojectTo install with conda:
- First add the required channels
$ conda config --add channels https://conda.anaconda.org/conda-forge $ conda config --add channels https://conda.anaconda.org/domdfcoding
- Then install
$ conda install sphinx-pyproject
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.
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})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.