Usage¶

Enable sphinx_packaging by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_packaging',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Directives¶

.. tconf:: name¶

Used to document a TOML configuration field, for example in PEP 621 metadata.

:type: (string)¶: Indicates the field’s type.

:required: (flag)¶: Indicates the whether a value is required for the field.

:default: (string)¶: Indicates the default value for the field.

:noindex: (flag)¶: Disables the index entry and cross-referencing for this field.

Examples:

.. tconf:: project.name
    :type: :toml:`String`
    :required: True

    The name of the project.

.. tconf:: project.version
    :type: :toml:`String`
    :required: True

    The version of the project as supported by :pep:`440`.

.. tconf:: description
    :type: :toml:`String`
    :default: ``'This is the description'``
    :required: False

    A short summary description of the project.

project.name¶: Type: String

Required: True

The name of the project.

project.version¶: Type: String

Required: True

The version of the project as supported by PEP 440.

description¶: Type: String

Required: False

Default: 'This is the description'

A short summary description of the project.

Roles¶

sphinx_packaging provides the following roles:

:pep:¶

Creates a cross-reference to a Python Enhancement Proposal.

The text “PEP NNN” is inserted into the document, and with supported builders is a hyperlink to the online copy of the specified PEP. This role also generates an appropriate index entry.

You can link to a specific section by writing :pep:`number#anchor`.

A custom title can also be added to the link by writing :pep:`title <number#anchor>`. Unlike the version of this directive which ships with Sphinx, the link is not shown in bold when there is a custom title.

Examples:

:pep:`621`

:pep:`503#normalized-names`

.. seealso:: The :pep:`specification <427>` for wheels.

PEP 621

PEP 503#normalized-names

See also

The specification for wheels.

:pep621:¶

Creates a cross-reference to a section in PEP 621, typically the name of a field in pyproject.toml.

The title of the directive (either implicit, :pep621:`title`, or explicit :pep621:`title <target>`) is inserted into the document. With supported builders is a hyperlink to the specified heading in the online copy of the PEP. This role also generates an appropriate index entry.

Examples:

The :pep621:`name` field must be provided and cannot be :pep621:`dynamic`.

:pep621:`Version <version>` may be required by some backend,
but can be determined dynamically by others.

:pep621:`authors` and :pep621:`maintainers` both point to the same section.

The name field must be provided and cannot be dynamic.

Version may be required by some backend, but can be determined dynamically by others.

authors and maintainers both point to the same section.

:core-meta:¶

Creates a cross-reference to a field in the Python core metadata.

The title of the directive (either implicit, :core-meta:`title`, or explicit :core-meta:`title <target>`) is inserted into the document. With supported builders is a hyperlink to the specified field in the specification on packaging.python.org. This role also generates an appropriate index entry.

Examples:

:core-meta:`Supported-Platform (Multiple Use) <Supported-Platform>` specifies the OS and CPU
for which the binary distribution was compiled.

The project's :core-meta:`description` may have multiple lines.

:pep621:`requires-python` in ``pyproject.toml`` maps to :core-meta:`Requires-Python`

Supported-Platform (Multiple Use) specifies the OS and CPU for which the binary distribution was compiled.

The project’s description may have multiple lines.

requires-python in pyproject.toml maps to Requires-Python

:toml:¶

Creates a cross-reference to a section in the TOML specification.

The title of the directive (either implicit, :toml:`title`, or explicit :toml:`title <target>`) is inserted into the document. With supported builders is a hyperlink to section in the web version of the specification. This role also generates an appropriate index entry.

Examples:

TOML's :toml:`string` type accepts either single or double quotes.

:toml:`Inline Tables <Inline Table>` must be on a single line.

There are four date/time types in TOML:

* :toml:`Offset Date-Time`
* :toml:`Local Date-Time`
* :toml:`Local Date`
* :toml:`!Local Time`

TOML’s string type accepts either single or double quotes.

Inline Tables must be on a single line.

There are four date/time types in TOML:

The last xref will not appear in the index because the target is prefixed with a !. This also works when there is an explicit title:

The following xrefs are not indexed: :toml:`!Float`, :toml:`array <!Array>`.

The following xrefs are not indexed: Float, array.

Click here to see the index.

:tconf:¶

Role which provides a cross-reference to a tconf directive.

Examples:

:tconf:`project.name` and :tconf:`~project.version` are required.
Some backends may be able to determine a value for :tconf:`version` dynamically.

:tconf:`description` will be displayed this towards the top of the project page on PyPI.

Links can also be written with a shorter name: :tconf:`~.name`.

project.name and version are required. Some backends may be able to determine a value for version dynamically.

description will be displayed this towards the top of the project page on PyPI.

Links can also be written with a shorter name: name.

Configuration¶

toml_spec_version¶

Type: string
Required: False
Default: 1.0.0

The version of the TOML specification to link to.

For example, this documentation links to v0.5.0 with the following setting:

# conf.py
toml_spec_version = "0.5.0"

tconf_show_full_name¶

Type: bool
Required: False
Default: True

Whether to show the full name for field.

For example, with tconf_show_full_name = True:

project.description: Type: String

And with tconf_show_full_name = False:

description: Type: String