#################
sphinx-pyproject
#################
.. start short_desc
**Move some of your Sphinx configuration into pyproject.toml**
.. end short_desc
.. start shields
.. list-table::
:stub-columns: 1
:widths: 10 90
* - Docs
- |docs| |docs_check|
* - Tests
- |actions_linux| |actions_windows| |actions_macos| |coveralls|
* - PyPI
- |pypi-version| |supported-versions| |supported-implementations| |wheel|
* - Anaconda
- |conda-version| |conda-platform|
* - Activity
- |commits-latest| |commits-since| |maintained| |pypi-downloads|
* - QA
- |codefactor| |actions_flake8| |actions_mypy|
* - Other
- |license| |language| |requires|
.. |docs| image:: https://img.shields.io/readthedocs/sphinx-pyproject/latest?logo=read-the-docs
:target: https://sphinx-pyproject.readthedocs.io/en/latest
:alt: Documentation Build Status
.. |docs_check| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Docs%20Check/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Docs+Check%22
:alt: Docs Check Status
.. |actions_linux| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Linux/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Linux%22
:alt: Linux Test Status
.. |actions_windows| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Windows/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Windows%22
:alt: Windows Test Status
.. |actions_macos| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/macOS/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22macOS%22
:alt: macOS Test Status
.. |actions_flake8| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Flake8/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Flake8%22
:alt: Flake8 Status
.. |actions_mypy| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/mypy/badge.svg
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22mypy%22
:alt: mypy status
.. |requires| image:: https://dependency-dash.repo-helper.uk/github/sphinx-toolbox/sphinx-pyproject/badge.svg
:target: https://dependency-dash.repo-helper.uk/github/sphinx-toolbox/sphinx-pyproject/
:alt: Requirements Status
.. |coveralls| image:: https://img.shields.io/coveralls/github/sphinx-toolbox/sphinx-pyproject/master?logo=coveralls
:target: https://coveralls.io/github/sphinx-toolbox/sphinx-pyproject?branch=master
:alt: Coverage
.. |codefactor| image:: https://img.shields.io/codefactor/grade/github/sphinx-toolbox/sphinx-pyproject?logo=codefactor
:target: https://www.codefactor.io/repository/github/sphinx-toolbox/sphinx-pyproject
:alt: CodeFactor Grade
.. |pypi-version| image:: https://img.shields.io/pypi/v/sphinx-pyproject
:target: https://pypi.org/project/sphinx-pyproject/
:alt: PyPI - Package Version
.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/sphinx-pyproject?logo=python&logoColor=white
:target: https://pypi.org/project/sphinx-pyproject/
:alt: PyPI - Supported Python Versions
.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/sphinx-pyproject
:target: https://pypi.org/project/sphinx-pyproject/
:alt: PyPI - Supported Implementations
.. |wheel| image:: https://img.shields.io/pypi/wheel/sphinx-pyproject
:target: https://pypi.org/project/sphinx-pyproject/
:alt: PyPI - Wheel
.. |conda-version| image:: https://img.shields.io/conda/v/domdfcoding/sphinx-pyproject?logo=anaconda
:target: https://anaconda.org/domdfcoding/sphinx-pyproject
:alt: Conda - Package Version
.. |conda-platform| image:: https://img.shields.io/conda/pn/domdfcoding/sphinx-pyproject?label=conda%7Cplatform
:target: https://anaconda.org/domdfcoding/sphinx-pyproject
:alt: Conda - Platform
.. |license| image:: https://img.shields.io/github/license/sphinx-toolbox/sphinx-pyproject
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/blob/master/LICENSE
:alt: License
.. |language| image:: https://img.shields.io/github/languages/top/sphinx-toolbox/sphinx-pyproject
:alt: GitHub top language
.. |commits-since| image:: https://img.shields.io/github/commits-since/sphinx-toolbox/sphinx-pyproject/v0.3.0
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/pulse
:alt: GitHub commits since tagged version
.. |commits-latest| image:: https://img.shields.io/github/last-commit/sphinx-toolbox/sphinx-pyproject
:target: https://github.com/sphinx-toolbox/sphinx-pyproject/commit/master
:alt: GitHub last commit
.. |maintained| image:: https://img.shields.io/maintenance/yes/2023
:alt: Maintenance
.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/sphinx-pyproject
:target: https://pypi.org/project/sphinx-pyproject/
:alt: PyPI - Downloads
.. end shields
Installation
--------------
.. start installation
``sphinx-pyproject`` can be installed from PyPI or Anaconda.
To install with ``pip``:
.. code-block:: bash
$ python -m pip install sphinx-pyproject
To install with ``conda``:
* First add the required channels
.. code-block:: bash
$ conda config --add channels https://conda.anaconda.org/conda-forge
$ conda config --add channels https://conda.anaconda.org/domdfcoding
* Then install
.. code-block:: bash
$ conda install sphinx-pyproject
.. end installation
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:
.. code-block:: python3
# 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:
.. code-block:: python
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.
Additionally the ``SphinxConfig`` class takes an optional parameter ``config_overrides`` that
can be used to dynamically update values from ``pyproject.toml``. This can be helpful for setting
dynamic values like ``version``.
.. code-block:: python3
# conf.py
from sphinx_pyproject import SphinxConfig
from myproject import __version__ as myproject_version
config = SphinxConfig("../pyproject.toml", globalns=globals(), config_overrides = {"version": myproject_version})
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.
.. _PEP 621: https://www.python.org/dev/peps/pep-0621/#authors-maintainers
.. _name: https://www.python.org/dev/peps/pep-0621/#name
.. _version: https://www.python.org/dev/peps/pep-0621/#version
.. _description: https://www.python.org/dev/peps/pep-0621/#description
.. _authors/maintainers: https://www.python.org/dev/peps/pep-0621/#authors-maintainers
.. _Sphinx configuration values: https://www.sphinx-doc.org/en/master/usage/configuration.html
.. _this project's pyproject.toml file: https://github.com/sphinx-toolbox/sphinx-pyproject/blob/master/pyproject.toml
Raw data
{
"_id": null,
"home_page": "https://github.com/sphinx-toolbox/sphinx-pyproject",
"name": "sphinx-pyproject",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "documentation,pep621,sphinx,toml",
"author": "",
"author_email": "Dominic Davis-Foster <dominic@davis-foster.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/39/97/aa8cec3da3e78f2c396b63332e2fe92fe43f7ff2ad19b3998735f28b0a7f/sphinx_pyproject-0.3.0.tar.gz",
"platform": "Windows",
"description": "\n#################\nsphinx-pyproject\n#################\n\n.. start short_desc\n\n**Move some of your Sphinx configuration into pyproject.toml**\n\n.. end short_desc\n\n\n.. start shields\n\n.. list-table::\n\t:stub-columns: 1\n\t:widths: 10 90\n\n\t* - Docs\n\t - |docs| |docs_check|\n\t* - Tests\n\t - |actions_linux| |actions_windows| |actions_macos| |coveralls|\n\t* - PyPI\n\t - |pypi-version| |supported-versions| |supported-implementations| |wheel|\n\t* - Anaconda\n\t - |conda-version| |conda-platform|\n\t* - Activity\n\t - |commits-latest| |commits-since| |maintained| |pypi-downloads|\n\t* - QA\n\t - |codefactor| |actions_flake8| |actions_mypy|\n\t* - Other\n\t - |license| |language| |requires|\n\n.. |docs| image:: https://img.shields.io/readthedocs/sphinx-pyproject/latest?logo=read-the-docs\n\t:target: https://sphinx-pyproject.readthedocs.io/en/latest\n\t:alt: Documentation Build Status\n\n.. |docs_check| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Docs%20Check/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Docs+Check%22\n\t:alt: Docs Check Status\n\n.. |actions_linux| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Linux/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Linux%22\n\t:alt: Linux Test Status\n\n.. |actions_windows| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Windows/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Windows%22\n\t:alt: Windows Test Status\n\n.. |actions_macos| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/macOS/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22macOS%22\n\t:alt: macOS Test Status\n\n.. |actions_flake8| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/Flake8/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22Flake8%22\n\t:alt: Flake8 Status\n\n.. |actions_mypy| image:: https://github.com/sphinx-toolbox/sphinx-pyproject/workflows/mypy/badge.svg\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/actions?query=workflow%3A%22mypy%22\n\t:alt: mypy status\n\n.. |requires| image:: https://dependency-dash.repo-helper.uk/github/sphinx-toolbox/sphinx-pyproject/badge.svg\n\t:target: https://dependency-dash.repo-helper.uk/github/sphinx-toolbox/sphinx-pyproject/\n\t:alt: Requirements Status\n\n.. |coveralls| image:: https://img.shields.io/coveralls/github/sphinx-toolbox/sphinx-pyproject/master?logo=coveralls\n\t:target: https://coveralls.io/github/sphinx-toolbox/sphinx-pyproject?branch=master\n\t:alt: Coverage\n\n.. |codefactor| image:: https://img.shields.io/codefactor/grade/github/sphinx-toolbox/sphinx-pyproject?logo=codefactor\n\t:target: https://www.codefactor.io/repository/github/sphinx-toolbox/sphinx-pyproject\n\t:alt: CodeFactor Grade\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/sphinx-pyproject\n\t:target: https://pypi.org/project/sphinx-pyproject/\n\t:alt: PyPI - Package Version\n\n.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/sphinx-pyproject?logo=python&logoColor=white\n\t:target: https://pypi.org/project/sphinx-pyproject/\n\t:alt: PyPI - Supported Python Versions\n\n.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/sphinx-pyproject\n\t:target: https://pypi.org/project/sphinx-pyproject/\n\t:alt: PyPI - Supported Implementations\n\n.. |wheel| image:: https://img.shields.io/pypi/wheel/sphinx-pyproject\n\t:target: https://pypi.org/project/sphinx-pyproject/\n\t:alt: PyPI - Wheel\n\n.. |conda-version| image:: https://img.shields.io/conda/v/domdfcoding/sphinx-pyproject?logo=anaconda\n\t:target: https://anaconda.org/domdfcoding/sphinx-pyproject\n\t:alt: Conda - Package Version\n\n.. |conda-platform| image:: https://img.shields.io/conda/pn/domdfcoding/sphinx-pyproject?label=conda%7Cplatform\n\t:target: https://anaconda.org/domdfcoding/sphinx-pyproject\n\t:alt: Conda - Platform\n\n.. |license| image:: https://img.shields.io/github/license/sphinx-toolbox/sphinx-pyproject\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/blob/master/LICENSE\n\t:alt: License\n\n.. |language| image:: https://img.shields.io/github/languages/top/sphinx-toolbox/sphinx-pyproject\n\t:alt: GitHub top language\n\n.. |commits-since| image:: https://img.shields.io/github/commits-since/sphinx-toolbox/sphinx-pyproject/v0.3.0\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/pulse\n\t:alt: GitHub commits since tagged version\n\n.. |commits-latest| image:: https://img.shields.io/github/last-commit/sphinx-toolbox/sphinx-pyproject\n\t:target: https://github.com/sphinx-toolbox/sphinx-pyproject/commit/master\n\t:alt: GitHub last commit\n\n.. |maintained| image:: https://img.shields.io/maintenance/yes/2023\n\t:alt: Maintenance\n\n.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/sphinx-pyproject\n\t:target: https://pypi.org/project/sphinx-pyproject/\n\t:alt: PyPI - Downloads\n\n.. end shields\n\nInstallation\n--------------\n\n.. start installation\n\n``sphinx-pyproject`` can be installed from PyPI or Anaconda.\n\nTo install with ``pip``:\n\n.. code-block:: bash\n\n\t$ python -m pip install sphinx-pyproject\n\nTo install with ``conda``:\n\n\t* First add the required channels\n\n\t.. code-block:: bash\n\n\t\t$ conda config --add channels https://conda.anaconda.org/conda-forge\n\t\t$ conda config --add channels https://conda.anaconda.org/domdfcoding\n\n\t* Then install\n\n\t.. code-block:: bash\n\n\t\t$ conda install sphinx-pyproject\n\n.. end installation\n\nUsage\n-------\n\nThe ``SphinxConfig`` class will load the configuration from ``pyproject.toml``.\nBy passing ``globalns=globals()`` to the class constructor, the keys parsed from the\n``pyproject.toml`` file will be added to the global namespace of the ``conf.py`` file.\n\nFor example:\n\n.. code-block:: python3\n\n\t# conf.py\n\n\tfrom sphinx_pyproject import SphinxConfig\n\n\tconfig = SphinxConfig(\"../pyproject.toml\", globalns=globals())\n\n\tauthor # This name *looks* to be undefined, but it isn't.\n\nThe ``SphinxConfig`` class also provides a ``collections.abc.Mapping`` interface.\nIf you are going to override or modify one of the configuration values after parsing it,\nthe recommended approach is to explicitly assign the name:\n\n.. code-block:: python\n\n\textensions = config[\"extensions\"]\n\textensions.append(\"sphinx.ext.autodoc\")\n\nThis will prevent warnings from linters etc., but is not necessary for Sphinx to see the configuration.\n\nAdditionally the ``SphinxConfig`` class takes an optional parameter ``config_overrides`` that\ncan be used to dynamically update values from ``pyproject.toml``. This can be helpful for setting\ndynamic values like ``version``.\n\n.. code-block:: python3\n\n\t# conf.py\n\tfrom sphinx_pyproject import SphinxConfig\n\n\tfrom myproject import __version__ as myproject_version\n\n\tconfig = SphinxConfig(\"../pyproject.toml\", globalns=globals(), config_overrides = {\"version\": myproject_version})\n\n\nConfiguration\n^^^^^^^^^^^^^^^\n\n``sphinx-pyproject`` parses the configuration from the ``[project]`` and ``[tool.sphinx-pyproject]`` tables in ``pyproject.toml``.\nThe ``[project]`` table is defined in `PEP 621`_.\n``sphinx-pyproject`` only uses the following keys:\n\n* name_ \u2013 The name of the project.\n* version_ \u2013 The version of the project.\n* description_ \u2013 The summary description of the project.\n* One of `authors/maintainers`_.\n\nThe remaining `Sphinx configuration values`_ can be provided in the ``[tool.sphinx-pyproject]`` table.\n\nSee `this project's pyproject.toml file`_ for an example of this configuration.\n\n.. _PEP 621: https://www.python.org/dev/peps/pep-0621/#authors-maintainers\n.. _name: https://www.python.org/dev/peps/pep-0621/#name\n.. _version: https://www.python.org/dev/peps/pep-0621/#version\n.. _description: https://www.python.org/dev/peps/pep-0621/#description\n.. _authors/maintainers: https://www.python.org/dev/peps/pep-0621/#authors-maintainers\n.. _Sphinx configuration values: https://www.sphinx-doc.org/en/master/usage/configuration.html\n.. _this project's pyproject.toml file: https://github.com/sphinx-toolbox/sphinx-pyproject/blob/master/pyproject.toml\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Move some of your Sphinx configuration into pyproject.toml",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://sphinx-pyproject.readthedocs.io/en/latest",
"Homepage": "https://github.com/sphinx-toolbox/sphinx-pyproject",
"Issue Tracker": "https://github.com/sphinx-toolbox/sphinx-pyproject/issues",
"Source Code": "https://github.com/sphinx-toolbox/sphinx-pyproject"
},
"split_keywords": [
"documentation",
"pep621",
"sphinx",
"toml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "90d589cb47c6399fd57ca451af15361499813c5d53e588cb6e00d89411ce724f",
"md5": "0aa68ae8fa23f82c9f04716a4716a835",
"sha256": "3aca968919f5ecd390f96874c3f64a43c9c7fcfdc2fd4191a781ad9228501b52"
},
"downloads": -1,
"filename": "sphinx_pyproject-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0aa68ae8fa23f82c9f04716a4716a835",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 23076,
"upload_time": "2023-08-18T21:43:43",
"upload_time_iso_8601": "2023-08-18T21:43:43.808931Z",
"url": "https://files.pythonhosted.org/packages/90/d5/89cb47c6399fd57ca451af15361499813c5d53e588cb6e00d89411ce724f/sphinx_pyproject-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3997aa8cec3da3e78f2c396b63332e2fe92fe43f7ff2ad19b3998735f28b0a7f",
"md5": "b99f57ce33388bb0eae35484310603c8",
"sha256": "efc4ee9d96f579c4e4ed1ac273868c64565e88c8e37fe6ec2dc59fbcd57684ab"
},
"downloads": -1,
"filename": "sphinx_pyproject-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b99f57ce33388bb0eae35484310603c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7695,
"upload_time": "2023-08-18T21:43:45",
"upload_time_iso_8601": "2023-08-18T21:43:45.473103Z",
"url": "https://files.pythonhosted.org/packages/39/97/aa8cec3da3e78f2c396b63332e2fe92fe43f7ff2ad19b3998735f28b0a7f/sphinx_pyproject-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 21:43:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sphinx-toolbox",
"github_project": "sphinx-pyproject",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "dom-toml",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "domdf-python-tools",
"specs": [
[
">=",
"2.7.0"
]
]
}
],
"tox": true,
"lcname": "sphinx-pyproject"
}
JSON
