Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This normalizes the description of the configuration value so that its default value's unit is the same as the internal one (i.e., seconds).
This commit fixes the issue of `objects.inv` denoting object names, whilst the `external` role only allows for role names.
As an example, take the `objects.inv` for the sphinx documentation, which contains:
```
py:function
compile : usage/domains/python.html#compile
```
A user might understandably expect that they could reference this using `` :external:py:function:`compile` ``, but actually this would previously error with:
```
WARNING: role for external cross-reference not found: py:function
```
this is because, `function` is the object type, yet `external` expects the related role name `func`.
It should not be necessary for the user to know about this distinction,
so in this commit, we add logic, to first look if the name relates to a role name (as previous, to not be back-breaking) but, if not, then also look if the name relates to an object that has a known role and, if so, use that.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
* The directive option ``:noindex:`` was renamed to ``:no-index:``.
* The directive option ``:noindexentry:`` was renamed to ``:no-index-entry:``.
* The directive option ``:nocontentsentry:`` was renamed to ``:no-contents-entry:``.
The previous names are retained as aliases, but will be deprecated
and removed in a future version of Sphinx (9.0 or later).
The current implementation of ``sphinx.ext.coverage`` outputs which
methods,classes, and functions are documented.
This commit adds a short summary of this report in terms of
``documented objects / total number of objects``,
both per module and total.
The purpose of this is to support
a currently not mainstream but relevant use-case:
a coverage report on the number of objects that are documented.
By having the statistics on the report or on the stdout,
a regex expression can capture the coverage percentage
(e.g. ``re.search(r'TOTAL.*?([0-9.]{4,6}\%)', d).group(1)``)
and use it e.g. in another report, a status badge, etc.
Two options were added to the configuration to allow a table
to be printed in the report and/or to stdout.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* Generic classes can be documented with ``.. py:class::`` using PEP 695 syntax:
.. code:: rst
.. py:class:: Sequence[T]
* Generic functions can be documented with ``.. py:function::`` using PEP 695 syntax:
.. code:: rst
.. py:function:: foo[T](x: T)
* Default values for type bounds are supported.
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
