sphinx-pyproject 0.2.0

Move some of your Sphinx configuration into pyproject.toml

Move some of your Sphinx configuration into pyproject.toml

Docs
Tests
PyPI
Anaconda
Activity
QA
Other

Installation

sphinx-pyproject can be installed from PyPI or Anaconda.

To install with pip:

$ python -m pip install sphinx-pyproject

To 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

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.

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.