Registry / devops / sphinx-pyproject

sphinx-pyproject

library0.3.0pypypi✓ verified 85d ago

sphinx-pyproject is a Python library that enables you to move parts of your Sphinx documentation configuration into your `pyproject.toml` file, promoting a centralized project configuration. The current version is 0.3.0, released in August 2023. While releases are infrequent, the project remains actively maintained.

devops

pip install sphinx-pyproject

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · SPHINX-PYPROJECT

sphinx-pyproject

devopspythonv0.3.0

Install

1.9s avg

Import

114ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.118s · 19.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.109s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SphinxConfig

✓ from sphinx_pyproject import SphinxConfig

To integrate `sphinx-pyproject` with your Sphinx project, first define your project's metadata and Sphinx-specific configurations in your `pyproject.toml` file under the `[project]` and `[tool.sphinx-pyproject]` tables. Then, in your `conf.py` file, import `SphinxConfig` and instantiate it, passing the path to your `pyproject.toml` and `globalns=globals()` to make the configuration values available in the `conf.py` namespace.

# pyproject.toml [project] name = "my-awesome-project" version = "0.1.0" description = "My awesome project description." authors = [{name = "Your Name", email = "you@example.com"}] [tool.sphinx-pyproject] project = "My Awesome Project Docs" copyright = "2026, Your Name" extensions = [ "sphinx.ext.autodoc", "sphinx.ext.napoleon" ] html_theme = "furo" # conf.py import os import sys sys.path.insert(0, os.path.abspath('.')) # Adjust this path to your project root if needed from sphinx_pyproject import SphinxConfig # Load configuration from pyproject.toml and make variables available globally in conf.py config = SphinxConfig("../pyproject.toml", globalns=globals()) # You can also access values directly from the config object: # project_name = config["project"] # print(project_name) # If globalns=globals() is used, you can access directly: # print(project) # print(copyright)

Debug

Known issues

gotchaWhen using Poetry for project management, its `[tool.poetry]` table does not fully adhere to PEP 621 for project metadata. If you intend to pull project metadata from Poetry's table, you must explicitly pass `style="poetry"` to the `SphinxConfig` constructor (e.g., `SphinxConfig("../pyproject.toml", style="poetry")`). The default `style` is `"pep621"`.

fix

Initialize SphinxConfig with `style="poetry"` for Poetry-managed projects.

affects: >=0.2.0

gotchaFor configuration values loaded from `pyproject.toml` (e.g., `project`, `copyright`) to be directly accessible as global variables in your `conf.py` file, you must pass `globalns=globals()` to the `SphinxConfig` constructor. Otherwise, you will need to access all values through the `config` object (e.g., `config["project"]`).

fix

Add `globalns=globals()` to the `SphinxConfig` instantiation, or explicitly retrieve values via `config['key']`.

affects: All versions

deprecatedThe `SphinxConfig` constructor gained the `style` argument in version 0.2.0 and the `config_overrides` argument in version 0.3.0. While these are additive, be aware of their introduction if maintaining compatibility with older, more specific constructor calls that might have relied on implicit defaults or fewer arguments.

fix

Review your `SphinxConfig` instantiation if upgrading from very old versions to ensure compatibility with new arguments, particularly if using positional arguments or relying on default behavior for `style`.

affects: <0.2.0, <0.3.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sphinx_pyproject'

The `sphinx-pyproject` package is not installed in the active Python environment.

fix

Install the package: `pip install sphinx-pyproject`

KeyError: 'my_config_key' (or similar)

You are trying to access a configuration key (e.g., `config['my_config_key']`) that is not defined in the `[tool.sphinx-pyproject]` section of your `pyproject.toml` file.

fix

Ensure the key exists and is correctly spelled under the `[tool.sphinx-pyproject]` table in your `pyproject.toml`. For example: `[tool.sphinx-pyproject] my_config_key = "value"`

NameError: name 'project' is not defined (or 'copyright', 'extensions', etc.) in conf.py

You are attempting to use configuration values as global variables directly in `conf.py` without providing the `globalns=globals()` argument to `SphinxConfig`.

fix

Modify your `SphinxConfig` instantiation to `config = SphinxConfig("../pyproject.toml", globalns=globals())`. Alternatively, access the values directly from the `config` object: `project_name = config["project"]`.

Upgrade

Version history

0.3.0latest on PyPI · released Aug 18, 2023

Audit

Dependencies

Sphinxrequiredsphinx-pyproject is a Sphinx extension and requires Sphinx to function.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/sphinx-toolbox/sphinx-pyproject ↗

packagehttps://pypi.org/project/sphinx-pyproject/ ↗

docshttps://sphinx-pyproject.readthedocs.io/en/latest ↗