docs: allow for Sphinx directives in changelogs

.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

.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

CHANGELOG.rst

@@ -24,11 +24,11 @@ pytest 5.3.0 (2019-11-19)
 Deprecations
 ------------
 
-- `#6179 <https://github.com/pytest-dev/pytest/issues/6179>`_: The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, given
+- `#6179 <https://github.com/pytest-dev/pytest/issues/6179>`_: The default value of :confval:`junit_family` option will change to ``"xunit2"`` in pytest 6.0, given
   that this is the version supported by default in modern tools that manipulate this type of file.
 
   In order to smooth the transition, pytest will issue a warning in case the ``--junitxml`` option
-  is given in the command line but ``junit_family`` is not explicitly configured in ``pytest.ini``.
+  is given in the command line but :confval:`junit_family` is not explicitly configured in ``pytest.ini``.
 
   For more information, `see the docs <https://docs.pytest.org/en/latest/deprecations.html#junit-family-default-value-change-to-xunit2>`__.
 
@@ -49,31 +49,31 @@ Features
   provide feedback.
 
 
-- `#4730 <https://github.com/pytest-dev/pytest/issues/4730>`_: When ``sys.pycache_prefix`` (Python 3.8+) is set, it will be used by pytest to cache test files changed by the assertion rewriting mechanism.
+- `#4730 <https://github.com/pytest-dev/pytest/issues/4730>`_: When :py:data:`sys.pycache_prefix` (Python 3.8+) is set, it will be used by pytest to cache test files changed by the assertion rewriting mechanism.
 
   This makes it easier to benefit of cached ``.pyc`` files even on file systems without permissions.
 
 
 - `#5515 <https://github.com/pytest-dev/pytest/issues/5515>`_: Allow selective auto-indentation of multiline log messages.
 
   Adds command line option ``--log-auto-indent``, config option
-  ``log_auto_indent`` and support for per-entry configuration of
-  indentation behavior on calls to ``logging.log()``.
+  :confval:`log_auto_indent` and support for per-entry configuration of
+  indentation behavior on calls to :py:func:`python:logging.log()`.
 
-  Alters the default for auto-indention from ``on`` to ``off``. This
+  Alters the default for auto-indention from ``"on"`` to ``"off"``. This
   restores the older behavior that existed prior to v4.6.0. This
   reversion to earlier behavior was done because it is better to
   activate new features that may lead to broken tests explicitly
   rather than implicitly.
 
 
-- `#5914 <https://github.com/pytest-dev/pytest/issues/5914>`_: `testdir <https://docs.pytest.org/en/latest/reference.html#testdir>`__ learned two new functions, `no_fnmatch_line <https://docs.pytest.org/en/latest/reference.html#_pytest.pytester.LineMatcher.no_fnmatch_line>`_ and
-  `no_re_match_line <https://docs.pytest.org/en/latest/reference.html#_pytest.pytester.LineMatcher.no_re_match_line>`_.
+- `#5914 <https://github.com/pytest-dev/pytest/issues/5914>`_: :ref:`testdir` learned two new functions, :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` and
+  :py:func:`~_pytest.pytester.LineMatcher.no_re_match_line`.
 
   The functions are used to ensure the captured text *does not* match the given
   pattern.
 
-  The previous idiom was to use ``re.match``:
+  The previous idiom was to use :py:func:`python:re.match`:
 
   .. code-block:: python
 

changelog/5914.bugfix.rst

@@ -1 +1 @@
-pytester: fix ``no_fnmatch_line`` when used after positive matching.
+pytester: fix :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` when used after positive matching.

changelog/6082.bugfix.rst

@@ -1 +1 @@
-Fix line detection for doctest samples inside ``property`` docstrings, as a workaround to `bpo-17446 <https://bugs.python.org/issue17446>`__.
+Fix line detection for doctest samples inside :py:class:`python:property` docstrings, as a workaround to `bpo-17446 <https://bugs.python.org/issue17446>`__.

changelog/6231.improvement.rst

@@ -1 +1 @@
-Improve check for misspelling of ``pytest.mark.parametrize``.
+Improve check for misspelling of :ref:`pytest.mark.parametrize ref`.

changelog/6255.bugfix.rst

@@ -1,3 +1,4 @@
-Clear the ``sys.last_traceback``, ``sys.last_type`` and ``sys.last_value``
-attributes by deleting them instead of setting them to ``None``. This better
-matches the behaviour of the Python standard library.
+Clear the :py:data:`sys.last_traceback`, :py:data:`sys.last_type`
+and :py:data:`sys.last_value` attributes by deleting them instead
+of setting them to ``None``. This better matches the behaviour of
+the Python standard library.

changelog/6257.improvement.rst

@@ -1 +1 @@
-Handle `exit.Exception` raised in `notify_exception` (via `pytest_internalerror`), e.g. when quitting pdb from post mortem.
+Handle :py:func:`_pytest.outcomes.exit` being used via :py:func:`~_pytest.hookspec.pytest_internalerror`, e.g. when quitting pdb from post mortem.

changelog/README.rst

@@ -34,3 +34,5 @@ If you are not sure what issue type to use, don't hesitate to ask in your PR.
 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.
+Alternatively you can also use ``tox -e docs-draft`` to build the documentation
+with the draft changelog (``doc/en/_build/changelog.html``).

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,30 @@
 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
 ~~~~~~~
 

tox.ini

@@ -58,10 +58,20 @@ 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
 commands =
-    sphinx-build -W --keep-going -b html . _build {posargs:}
+    sphinx-build -W --keep-going -b html doc/en doc/en/_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