API Reference

Move some of your Sphinx configuration into pyproject.toml.

Classes:

`SphinxConfig`([pyproject_file, globalns, …])	Read the Sphinx configuration from `pyproject.toml`.
`ProjectParser`()	Parser for PEP 621 metadata from `pyproject.toml`.
`PoetryProjectParser`()	Parser for poetry metadata from `pyproject.toml`.

class SphinxConfig(pyproject_file='../pyproject.toml', *, globalns=None, style='pep621', config_overrides=None)[source]

Bases: Mapping[str, Any]

Read the Sphinx configuration from pyproject.toml.

Parameters

pyproject_file (Union[str, Path, PathLike]) – The path to the pyproject.toml file. Default '../pyproject.toml'.
globalns (Optional[MutableMapping]) – The global namespace of the conf.py file. The variables parsed from the [tool.sphinx-pyproject] table will be added to this namespace. By default, or if explicitly None, this does not happen.
style (str) – Either pep621 (default), or poetry to read configuration from the [tool.poetry] table.
config_overrides (Optional[MutableMapping]) – Custom configuration overrides. This parameter can be used to dynamically update values from pyproject.toml. This can be used to patch dynamic values like version. By default, or if explicitly None, no config updates are performed.

Changed in version 0.2.0: Added the style keyword argument.

Changed in version 0.3.0: Added the config_overrides keyword argument.

Attributes:

`name`	The value of the project.name key in the PEP 621 metadata.
`version`	The value of the project.version key in the PEP 621 metadata.
`description`	The value of the project.description key in the PEP 621 metadata.
`author`	A string giving the names of the authors.

Methods:

`__getitem__`(item)	Returns the value of the given key in the `tool.sphinx-pyproject` table.
`__len__`()	Returns the number of keys in the `tool.sphinx-pyproject` table.
`__iter__`()	Returns an iterator over the keys in the `tool.sphinx-pyproject` table.

name

Type: str

The value of the project.name key in the PEP 621 metadata.

Underscores are replaced by dashes but PEP 508 normalization is not applied.

The recommendation is to assign this to the project variable in conf.py:

from sphinx_pyproject import SphinxConfig

config = SphinxConfig()
project = config.name

version

Type: str

The value of the project.version key in the PEP 621 metadata.

Converted to a string if the value was a number in the pyproject.toml file.

description

Type: str

The value of the project.description key in the PEP 621 metadata.

author

Type: str

A string giving the names of the authors.

This is parsed from the project.authors key in the PEP 621 metadata, or the project.maintainers key as a fallback.

The names are joined together, e.g.:

# pyproject.toml

[[project.authors]]
name = "Dominic Davis-Foster"

[[project.authors]]
name = "Joe Bloggs"

[[project.authors]]
name = "Jane Doe"

>>> SphinxConfig("pyproject.toml").author
'Dominic Davis-Foster, Joe Bloggs and Jane Doe'

__getitem__(item)[source]

Returns the value of the given key in the tool.sphinx-pyproject table.

Parameters: item (str)
Return type: Any

__len__()[source]

Returns the number of keys in the tool.sphinx-pyproject table.

Return type: int

__iter__()[source]

Returns an iterator over the keys in the tool.sphinx-pyproject table.

Return type: Iterator[str]

class ProjectParser[source]

Bases: AbstractConfigParser

Parser for PEP 621 metadata from pyproject.toml.

Methods:

`get_namespace`(filename, config)	Returns the `[project]` table in a `project.toml` file.
`parse_name`(config)	Parse the name key.
`parse_version`(config)	Parse the version key.
`parse_description`(config)	Parse the description key.
`parse_author`(config)	Parse the authors/maintainers key.
`parse`(config[, set_defaults])	Parse the TOML configuration.

static get_namespace(filename, config)[source]

Returns the [project] table in a project.toml file.

Parameters

filename (PathPlus) – The filename the TOML data was read from. Used in error messages.
config (Dict[str, Any]) – The data from the TOML file.

New in version 0.2.0.

Return type: Dict[str, Any]

parse_name(config)[source]

Parse the name key.

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the [project] table.
Return type: str

parse_version(config)[source]

Parse the version key.

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the [project] table.
Return type: str

parse_description(config)[source]

Parse the description key.

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the [project] table.
Return type: str

static parse_author(config)[source]

Parse the authors/maintainers key.

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the [project] table.
Return type: str

parse(config, set_defaults=False)[source]

Parse the TOML configuration.

Parameters

config (Dict[str, Any])
set_defaults (bool) – Has no effect in this class. Default False.

Return type

Dict[str, Any]

class PoetryProjectParser[source]

Bases: ProjectParser

Parser for poetry metadata from pyproject.toml.

New in version 0.2.0.

Methods:

`get_namespace`(filename, config)	Returns the `[tool.poetry]` table in a `project.toml` file.
`parse_author`(config)	Parse poetry’s authors key.

static get_namespace(filename, config)[source]

Returns the [tool.poetry] table in a project.toml file.

Parameters

filename (PathPlus) – The filename the TOML data was read from. Used in error messages.
config (Dict[str, Any]) – The data from the TOML file.

Return type

Dict[str, Any]

static parse_author(config)[source]

Parse poetry’s authors key.

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the [tool.poetry] table.
Return type: str