docs: add docs-draft tox env, with generated towncrier draft

Author: blueyed

.gitignore

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

.travis.yml

@@ -65,7 +65,7 @@ jobs:
     - stage: baseline
       env: TOXENV=py36-xdist
       python: '3.6'
-    - env: TOXENV=linting,docs,doctesting PYTEST_COVERAGE=1
+    - env: TOXENV=linting,docs-draft,doctesting PYTEST_COVERAGE=1
       cache:
         directories:
           - $HOME/.cache/pre-commit

doc/en/changelog.rst

@@ -1,4 +1,16 @@
 
 .. _changelog:
 
+.. only:: changelog_towncrier_draft
+
+    ==============================
+    Draft changelog from towncrier
+    ==============================
+
+    .. include:: _changelog_towncrier_draft.rst
+
+    **End of DRAFT changelog**
+
+    ------------
+
 .. include:: ../../CHANGELOG.rst

doc/en/conf.py

@@ -20,6 +20,10 @@
 
 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,27 @@
 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:
+            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 +375,4 @@ def setup(app):
         objname="configuration value",
         indextemplate="pair: %s; configuration value",
     )
+    configure_logging(app)

tox.ini

@@ -63,6 +63,17 @@ deps = -r{toxinidir}/doc/en/requirements.txt
 commands =
     sphinx-build -W --keep-going -b html . _build {posargs:}
 
+[testenv:docs-draft]
+basepython = python3
+usedevelop = True
+deps =
+    -r{toxinidir}/doc/en/requirements.txt
+    towncrier
+whitelist_externals = sh
+commands =
+    sh -c 'towncrier --draft > doc/en/_changelog_towncrier_draft.rst'
+    sphinx-build -W --keep-going -b html doc/en doc/en/_build -t changelog_towncrier_draft {posargs:}
+
 [testenv:docs-checklinks]
 basepython = python3
 usedevelop = True