docs: move changelog to docs/en and allow sphinx directives (#6287)

docs: move changelog to docs/en and allow sphinx directives

.gitignore

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

.pre-commit-config.yaml

@@ -48,7 +48,7 @@ repos:
     -   id: rst
         name: rst
         entry: rst-lint --encoding utf-8
-        files: ^(CHANGELOG.rst|HOWTORELEASE.rst|README.rst|TIDELIFT.rst|changelog/.*)$
+        files: ^(HOWTORELEASE.rst|README.rst|TIDELIFT.rst)$
         language: python
         additional_dependencies: [pygments, restructuredtext_lint]
     -   id: changelogs-rst

changelog/README.rst

@@ -31,6 +31,7 @@ changelog using that instead.
 If you are not sure what issue type to use, don't hesitate to ask in your PR.
 
 ``towncrier`` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries
-other than ``features`` it is usually better to stick to a single paragraph to keep it concise. You can install
-``towncrier`` and then run ``towncrier --draft``
-if you want to get a preview of how your change will look in the final release notes.
+other than ``features`` it is usually better to stick to a single paragraph to keep it concise.
+
+You can also run ``tox -e docs`` to build the documentation
+with the draft changelog (``doc/en/_build/changelog.html``) if you want to get a preview of how your change will look in the final release notes.

doc/en/conf.py

@@ -20,6 +20,10 @@ import sys
 
 from _pytest import __version__ as version
 
+if False:  # TYPE_CHECKING
+    import sphinx.application
+
+
 release = ".".join(version.split(".")[:2])
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -342,7 +346,30 @@ texinfo_documents = [
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 
-def setup(app):
+def configure_logging(app: "sphinx.application.Sphinx") -> None:
+    """Configure Sphinx's WarningHandler to handle (expected) missing include."""
+    import sphinx.util.logging
+    import 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:
     # from sphinx.ext.autodoc import cut_lines
     # app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
     app.add_object_type(
@@ -351,3 +378,4 @@ def setup(app):
         objname="configuration value",
         indextemplate="pair: %s; configuration value",
     )
+    configure_logging(app)

doc/en/reference.rst

@@ -463,6 +463,8 @@ monkeypatch
 .. autoclass:: _pytest.monkeypatch.MonkeyPatch
     :members:
 
+.. _testdir:
+
 testdir
 ~~~~~~~
 

pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
 [tool.towncrier]
 package = "pytest"
 package_dir = "src"
-filename = "CHANGELOG.rst"
+filename = "doc/en/changelog.rst"
 directory = "changelog/"
 title_format = "pytest {version} ({project_date})"
 template = "changelog/_template.rst"

scripts/release.py

@@ -85,12 +85,13 @@ def check_links():
     check_call(["tox", "-e", "docs-checklinks"])
 
 
-def pre_release(version):
+def pre_release(version, *, skip_check_links):
     """Generates new docs, release announcements and creates a local tag."""
     announce(version)
     regen()
     changelog(version, write_out=True)
     fix_formatting()
+    if not skip_check_links:
         check_links()
 
     msg = "Preparing release version {}".format(version)
@@ -114,8 +115,9 @@ def main():
     init(autoreset=True)
     parser = argparse.ArgumentParser()
     parser.add_argument("version", help="Release version")
+    parser.add_argument("--skip-check-links", action="store_true", default=False)
     options = parser.parse_args()
-    pre_release(options.version)
+    pre_release(options.version, skip_check_links=options.skip_check_links)
 
 
 if __name__ == "__main__":

tox.ini

@@ -58,10 +58,16 @@ commands = pre-commit run --all-files --show-diff-on-failure
 [testenv:docs]
 basepython = python3
 usedevelop = True
-changedir = doc/en
-deps = -r{toxinidir}/doc/en/requirements.txt
+deps =
+    -r{toxinidir}/doc/en/requirements.txt
+    towncrier
+whitelist_externals = sh
 commands =
-    sphinx-build -W --keep-going -b html . _build {posargs:}
+    sh -c 'towncrier --draft > doc/en/_changelog_towncrier_draft.rst'
+    # 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 -t changelog_towncrier_draft {posargs:}
 
 [testenv:docs-checklinks]
 basepython = python3
@@ -86,10 +92,10 @@ changedir = doc/en
 skipsdist = True
 basepython = python3
 deps =
-    sphinx
+    dataclasses
     PyYAML
     regendoc>=0.6.1
-    dataclasses
+    sphinx
 whitelist_externals =
     rm
     make
@@ -117,8 +123,8 @@ deps =
     colorama
     gitpython
     pre-commit>=1.11.0
-    towncrier
     wheel
+    towncrier
 commands = python scripts/release.py {posargs}
 
 [testenv:publish_gh_release_notes]