📝💅 Always render changelog draft @ Sphinx docs

The earlier implementation was generating a temporary file, when
the docs site was being built with `tox`. However, this was not
enabled in RTD and is hackish.
This patch integrates the `sphinxcontrib-towncrier` extension to
make it work in any environment where Sphinx docs are being built.

.gitignore

@@ -25,7 +25,6 @@ src/_pytest/_version.py
 
 doc/*/_build
 doc/*/.doctrees
-doc/*/_changelog_towncrier_draft.rst
 build/
 dist/
 *.egg-info

.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

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
 

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 @@ if TYPE_CHECKING:
     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 @@ extensions = [
     "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 @@ texinfo_documents = [
     )
 ]
 
+# -- 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 @@ intersphinx_mapping = {
 }
 
 
-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

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

scripts/towncrier-draft-to-file.py

@@ -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())

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=