sphinx-pyproject

Common errors

• ModuleNotFoundError: No module named 'sphinx_pyproject'

  cause 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)

  cause 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

  cause 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"]`.

Warnings

• gotcha When 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.
• gotcha For 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']`.
• deprecated The `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`.

Install

• pip install sphinx-pyproject Install from PyPI

Imports

• SphinxConfig

  from sphinx_pyproject import SphinxConfig

Quickstart

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)