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.
- 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.
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>`.
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
andversion
are required. Some backends may be able to determine a value forversion
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: stringRequired:
False
Default: 1.0.0The 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"