* 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>
This commit disables Sphinx's localisation features when reproducible
builds are requested, as determined by a non-empty SOURCE_DATE_EPOCH_
environment variable.
The `Reproducible Builds`_ project aims to provide confidence to
consumers of packaged software that the artefacts they're downloading
and installing have not been altered by the environment they were
built in, and can be replicated at a later date if required.
Builds of localised documentation using Sphinx currently account for
a large category of reproducible build testing failures, because the
builders intentionally use varying environment locales at build-time.
This can affect the contents of the ``objects.inv`` file.
During investigation, it turned out that many ``gettext``-localised
values (particularly in Python modules under ``sphinx.domains``) were
being translated at module-load-time and would not subsequently be
re-localised.
This creates two unusual effects:
1. Attempting to write a test case to build the same application in
two different languages was not initially possible, as the
first-loaded translation catalogue (as found in the
``sphinx.locale.translators`` global variable) would remain in-use
for subsequent application builds under different locales.
2. Localisation of strings could vary depending on whether the
relevant modules were loaded before or after the resource
catalogues were populated.
We fix this by performing all translations lazily so that module
imports can occur in any order and localisation of inventory entries
should occur only when translations of those items are requested.
Localisation can then be disabled by configuring the ``gettext``
language to the ISO-639-3 'undetermined' code (``'und'``), as this
should not have an associated translation catalogue. We also want to
prevent ``gettext`` from attempting to determine the host's locale
from environment variables (including ``LANGUAGE``).
.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
.. _Reproducible Builds: https://www.reproducible-builds.org/
Node.traverse() was marked as deprecated since docutils-0.18. Instead
of it, Node.findall() has been added as successor of traverse().
This applies a patch to docutils-0.17 or older to be available
Node.findall() and use it.
Removes the need for various translators from raising a
`NotImplementedError` exception when missing support for a specific node
type. docutils will already raise [1][2] a `NotImplementedError`
exception for these cases. This help reduce the implementation inside
Sphinx as well as prevents the possible undesired replication of
unknown-node handling with third-party extensions [3].
In most cases, generating a warning message for an unsupported node type
can be preferred. Providing an indication that a node is not supported
can be easier for a user of Sphinx to understand a limitation of a
builder over a generic "not implemented" exception. This commit takes
the logging call which is already used by `texinfo` and applies it to
the `SphinxTranslator` base class -- which any Sphinx translator
implementation can use.
[1]: https://repo.or.cz/docutils.git/blob/d169015ee0f412cffd69b33654d8a119d99bc0f3:/docutils/nodes.py#l2048
[2]: https://repo.or.cz/docutils.git/blob/53716a13b48128af6045139d3cd2909f61e7ed8e:/docutils/nodes.py#l1897
[3]: https://github.com/sphinx-doc/sphinx/issues/9921
Signed-off-by: James Knight <james.d.knight@live.com>
Add test objects so all builders gets exposed to the new nodes.
Make the fallback node post-transform change desc_inline as well.
Make the html4, latex, and text writers handle desc_inline.
Keep imports alphabetically sorted and their order homogeneous across
Python source files.
The isort project has more feature and is more active than the
flake8-import-order plugin.
Most issues caught were simply import ordering from the same module.
Where imports were purposefully placed out of order, tag with
isort:skip.
