mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
The Sphinx documentation generator
267fe9afa8
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> |
||
|---|---|---|
| .github | ||
| doc | ||
| sphinx | ||
| tests | ||
| utils | ||
| .codecov.yml | ||
| .git-blame-ignore-revs | ||
| .gitattributes | ||
| .gitignore | ||
| .mailmap | ||
| .readthedocs.yml | ||
| .ruff.toml | ||
| AUTHORS.rst | ||
| bindep.txt | ||
| CHANGES.rst | ||
| CODE_OF_CONDUCT.rst | ||
| CONTRIBUTING.rst | ||
| EXAMPLES.rst | ||
| LICENSE.rst | ||
| Makefile | ||
| package-lock.json | ||
| package.json | ||
| pyproject.toml | ||
| README.rst | ||
| tox.ini | ||
======== Sphinx ======== .. image:: https://img.shields.io/pypi/v/sphinx.svg :target: https://pypi.org/project/Sphinx/ :alt: Package on PyPI .. image:: https://github.com/sphinx-doc/sphinx/actions/workflows/main.yml/badge.svg :target: https://github.com/sphinx-doc/sphinx/actions/workflows/main.yml :alt: Build Status .. image:: https://readthedocs.org/projects/sphinx/badge/?version=master :target: https://www.sphinx-doc.org/ :alt: Documentation Status .. image:: https://img.shields.io/badge/License-BSD%202--Clause-blue.svg :target: https://opensource.org/licenses/BSD-2-Clause :alt: BSD 2 Clause **Sphinx makes it easy to create intelligent and beautiful documentation.** Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils. Features ======== * **Output formats**: HTML, PDF, plain text, EPUB, TeX, manual pages, and more * **Extensive cross-references**: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information * **Hierarchical structure**: easy definition of a document tree, with automatic links to siblings, parents and children * **Automatic indices**: general index as well as a module index * **Code highlighting**: automatic highlighting using the Pygments highlighter * **Templating**: Flexible HTML output using the Jinja 2 templating engine * **Extension ecosystem**: Many extensions are available, for example for automatic function documentation or working with Jupyter notebooks. * **Language Support**: Python, C, C++, JavaScript, mathematics, and many other languages through extensions. For more information, refer to `the documentation`_. Installation ============ The following command installs Sphinx from the `Python Package Index`_. You will need a working installation of Python and pip. .. code-block:: shell pip install -U sphinx Contributing ============ We appreciate all contributions! Refer to `the contributors guide`_ for information. .. _the documentation: https://www.sphinx-doc.org/ .. _the contributors guide: https://www.sphinx-doc.org/en/master/internals/contributing.html .. _Python Package Index: https://pypi.org/project/Sphinx/