diff --git a/.gitignore b/.gitignore index 9fccf93f7c3..c4557b33a1c 100644 --- a/.gitignore +++ b/.gitignore @@ -25,7 +25,6 @@ src/_pytest/_version.py doc/*/_build doc/*/.doctrees -doc/*/_changelog_towncrier_draft.rst build/ dist/ *.egg-info diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 04716fd2a6f..f7370f1bb98 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -20,6 +20,10 @@ build: 3.12 apt_packages: - inkscape + jobs: + post_checkout: + - git fetch --unshallow || true + - git fetch --tags || true formats: - epub diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index 3ab2307ee5d..7e32b943446 100644 --- a/doc/en/changelog.rst +++ b/doc/en/changelog.rst @@ -19,12 +19,15 @@ with advance notice in the **Deprecations** section of releases. we named the news folder changelog -.. only:: changelog_towncrier_draft +.. only:: not is_release - .. The 'changelog_towncrier_draft' tag is included by our 'tox -e docs', - but not on readthedocs. + To be included in v\ |release| (if present) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. include:: _changelog_towncrier_draft.rst + .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] + + Released versions + ^^^^^^^^^^^^^^^^^ .. towncrier release notes start diff --git a/doc/en/conf.py b/doc/en/conf.py index 738d07dc2f1..3e87003c510 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -15,6 +15,8 @@ # # The full version, including alpha/beta/rc tags. # The short X.Y version. +import os +from pathlib import Path import shutil from textwrap import dedent from typing import TYPE_CHECKING @@ -26,6 +28,16 @@ import sphinx.application +PROJECT_ROOT_DIR = Path(__file__).parents[2].resolve() +IS_RELEASE_ON_RTD = ( + os.getenv("READTHEDOCS", "False") == "True" + and os.environ["READTHEDOCS_VERSION_TYPE"] == "tag" +) +if IS_RELEASE_ON_RTD: + tags: set[str] + # pylint: disable-next=used-before-assignment + tags.add("is_release") # noqa: F821 + release = ".".join(version.split(".")[:2]) # If extensions (or modules to document with autodoc) are in another directory, @@ -72,6 +84,7 @@ "sphinx.ext.viewcode", "sphinx_removed_in", "sphinxcontrib_trio", + "sphinxcontrib.towncrier.ext", # provides `towncrier-draft-entries` directive ] # Building PDF docs on readthedocs requires inkscape for svg to pdf @@ -422,6 +435,13 @@ ) ] +# -- Options for towncrier_draft extension ----------------------------------- + +towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-version', 'sphinx-release' +towncrier_draft_include_empty = True +towncrier_draft_working_directory = PROJECT_ROOT_DIR +towncrier_draft_config_path = "pyproject.toml" # relative to cwd + intersphinx_mapping = { "pluggy": ("https://pluggy.readthedocs.io/en/stable", None), @@ -435,30 +455,6 @@ } -def configure_logging(app: "sphinx.application.Sphinx") -> None: - """Configure Sphinx's WarningHandler to handle (expected) missing include.""" - import logging - - import sphinx.util.logging - - class WarnLogFilter(logging.Filter): - def filter(self, record: logging.LogRecord) -> bool: - """Ignore warnings about missing include with "only" directive. - - Ref: https://github.com/sphinx-doc/sphinx/issues/2150.""" - if ( - record.msg.startswith('Problems with "include" directive path:') - and "_changelog_towncrier_draft.rst" in record.msg - ): - return False - return True - - logger = logging.getLogger(sphinx.util.logging.NAMESPACE) - warn_handler = [x for x in logger.handlers if x.level == logging.WARNING] - assert len(warn_handler) == 1, warn_handler - warn_handler[0].filters.insert(0, WarnLogFilter()) - - def setup(app: "sphinx.application.Sphinx") -> None: app.add_crossref_type( "fixture", @@ -488,8 +484,6 @@ def setup(app: "sphinx.application.Sphinx") -> None: indextemplate="pair: %s; hook", ) - configure_logging(app) - # legacypath.py monkey-patches pytest.Testdir in. Import the file so # that autodoc can discover references to it. import _pytest.legacypath # noqa: F401 diff --git a/doc/en/requirements.txt b/doc/en/requirements.txt index 6e7221d645a..e40a15f1f15 100644 --- a/doc/en/requirements.txt +++ b/doc/en/requirements.txt @@ -9,3 +9,4 @@ sphinxcontrib-svg2pdfconverter # See https://github.com/pytest-dev/pytest/pull/10578#issuecomment-1348249045. packaging furo +sphinxcontrib-towncrier diff --git a/scripts/towncrier-draft-to-file.py b/scripts/towncrier-draft-to-file.py deleted file mode 100644 index f771295a01f..00000000000 --- a/scripts/towncrier-draft-to-file.py +++ /dev/null @@ -1,18 +0,0 @@ -# mypy: disallow-untyped-defs -from subprocess import call -import sys - - -def main() -> int: - """ - Platform-agnostic wrapper script for towncrier. - Fixes the issue (#7251) where Windows users are unable to natively run tox -e docs to build pytest docs. - """ - with open( - "doc/en/_changelog_towncrier_draft.rst", "w", encoding="utf-8" - ) as draft_file: - return call(("towncrier", "--draft"), stdout=draft_file) - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/tox.ini b/tox.ini index 35b335a015d..dae89975467 100644 --- a/tox.ini +++ b/tox.ini @@ -88,11 +88,11 @@ deps = # https://github.com/twisted/towncrier/issues/340 towncrier<21.3.0 commands = - python scripts/towncrier-draft-to-file.py - # the '-t changelog_towncrier_draft' tags makes sphinx include the draft - # changelog in the docs; this does not happen on ReadTheDocs because it uses - # the standard sphinx command so the 'changelog_towncrier_draft' is never set there - sphinx-build -W --keep-going -b html doc/en doc/en/_build/html -t changelog_towncrier_draft {posargs:} + # Retrieve possibly missing commits: + -git fetch --unshallow + -git fetch --tags + + sphinx-build -W --keep-going -b html doc/en doc/en/_build/html {posargs:} setenv = # Sphinx is not clean of this warning. PYTHONWARNDEFAULTENCODING=