Sphinx's copyright substitution currently allows years identified as
the current year to be downgraded to previous years when
``SOURCE_DATE_EPOCH`` is configured, to assist reproducibility [1] of
documentation builds.
However, we have a test case ``test_html_multi_line_copyright``,
written in 2024, that mentioned a future year (2025).
Now that we have reached 2025, it is eligible for substitution when
``SOURCE_DATE_EPOCH`` is configured. Many buildsystems, such as those
used by Debian and Fedora, choose the most-recent packaging/commit
timestamp to use as `SOURCE_DATE_EPOCH`'s timestamp, since those
correspond sensibly to a time-of-build.
However, for the Sphinx 8.1.3 release including the updated
substitution logic, the year-of-release/commit was 2024. Thus, if a
commit/packaging date from that year is chosen, and
``SOURCE_DATE_EPOCH`` is configured when the unit tests run, the
``test_html_multi_line_copyright`` test will fail.
The fix suggested here is to explicitly unset ``SOURCE_DATE_EPOCH``
within ``test_html_multi_line_copyright``.
[1]: https://www.reproducible-builds.org/
Authored-by: Colin Watson <cjwatson@debian.org>
Co-authored-by: Colin Watson <cjwatson@debian.org>
Authored-by: James Addison <55152140+jayaddison@users.noreply.github.com>
Co-authored-by: James Addison <55152140+jayaddison@users.noreply.github.com>
Previously, there were two type preprocessing functions:
`_convert_type_spec` (used in Google-style docstrings) and
`_convert_numpy_type_spec` (used in Numpy-style docstrings).
The Google version simply applied type-alias translations or wrapped
the text in a `:py:class:` role.
The Numpy version does the same, plus adds special handling for keywords
`optional` and `default` and delimiter words `or`, `of`, and `and`. This
allows one to write in natural language, like `Array of int` instead of
`Array[int]` or `Widget, optional` instead of `Optional[Widget]` or
`Widget | None`. Numpy style is described in full at:
https://numpydoc.readthedocs.io/en/latest/format.html#parameters
This commit eliminates the distinction and allows Google-style
docstrings to use these preprocessing rules.
This puts all preprocessing code above both docstring classes, rather
than in between. This is in preparation to making both docstring classes
share the same preprocessing.
The streams-based interfaces in intersphinx and ``sphinx.util.inventory``
are clever, but also complex and prevent using compression methods
that don't support incrememntal decoding. This change refactors
``_fetch_inventory()`` to read all inventory content from disk or an
HTTP request at once.
