{"id":8673,"library":"sphinx-pyproject","title":"sphinx-pyproject","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-toolbox/sphinx-pyproject","tags":["sphinx","pyproject.toml","configuration","documentation"],"install":[{"cmd":"pip install sphinx-pyproject","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"sphinx-pyproject is a Sphinx extension and requires Sphinx to function.","package":"Sphinx"}],"imports":[{"symbol":"SphinxConfig","correct":"from sphinx_pyproject import SphinxConfig"}],"quickstart":{"code":"# pyproject.toml\n[project]\nname = \"my-awesome-project\"\nversion = \"0.1.0\"\ndescription = \"My awesome project description.\"\nauthors = [{name = \"Your Name\", email = \"you@example.com\"}]\n\n[tool.sphinx-pyproject]\nproject = \"My Awesome Project Docs\"\ncopyright = \"2026, Your Name\"\nextensions = [\n    \"sphinx.ext.autodoc\",\n    \"sphinx.ext.napoleon\"\n]\nhtml_theme = \"furo\"\n\n# conf.py\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.')) # Adjust this path to your project root if needed\n\nfrom sphinx_pyproject import SphinxConfig\n\n# Load configuration from pyproject.toml and make variables available globally in conf.py\nconfig = SphinxConfig(\"../pyproject.toml\", globalns=globals())\n\n# You can also access values directly from the config object:\n# project_name = config[\"project\"]\n# print(project_name)\n\n# If globalns=globals() is used, you can access directly:\n# print(project)\n# print(copyright)\n","lang":"python","description":"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."},"warnings":[{"fix":"Initialize SphinxConfig with `style=\"poetry\"` for Poetry-managed projects.","message":"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\"`.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Add `globalns=globals()` to the `SphinxConfig` instantiation, or explicitly retrieve values via `config['key']`.","message":"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\"]`).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"deprecated","affected_versions":"<0.2.0, <0.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package: `pip install sphinx-pyproject`","cause":"The `sphinx-pyproject` package is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'sphinx_pyproject'"},{"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\"`","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.","error":"KeyError: 'my_config_key' (or similar)"},{"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\"]`.","cause":"You are attempting to use configuration values as global variables directly in `conf.py` without providing the `globalns=globals()` argument to `SphinxConfig`.","error":"NameError: name 'project' is not defined (or 'copyright', 'extensions', etc.) in conf.py"}]}