diff --git a/.gitignore b/.gitignore index fc61c6ee612..83b6dbe7351 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,7 @@ src/_pytest/_version.py doc/*/_build doc/*/.doctrees +doc/*/_changelog_towncrier_draft.rst build/ dist/ *.egg-info diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d4196152f46..c3c874ed23d 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/.travis.yml b/.travis.yml index e3edbfe9b7c..633c5a9e676 100644 --- a/.travis.yml +++ b/.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 diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 30574f57493..7b3e776a08b 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -24,11 +24,11 @@ pytest 5.3.0 (2019-11-19) Deprecations ------------ -- `#6179 `_: The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, given +- `#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 `__. @@ -49,7 +49,7 @@ Features provide feedback. -- `#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 `_: 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. @@ -57,23 +57,23 @@ Features - `#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 `_: `testdir `__ learned two new functions, `no_fnmatch_line `_ and - `no_re_match_line `_. +- `#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 diff --git a/changelog/5914.bugfix.rst b/changelog/5914.bugfix.rst index b62b0b3c0a8..0a0493a0fd0 100644 --- a/changelog/5914.bugfix.rst +++ b/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. diff --git a/changelog/6082.bugfix.rst b/changelog/6082.bugfix.rst index 24d389257fc..2ff1d63cbd0 100644 --- a/changelog/6082.bugfix.rst +++ b/changelog/6082.bugfix.rst @@ -1 +1 @@ -Fix line detection for doctest samples inside ``property`` docstrings, as a workaround to `bpo-17446 `__. +Fix line detection for doctest samples inside :py:class:`python:property` docstrings, as a workaround to `bpo-17446 `__. diff --git a/changelog/6231.improvement.rst b/changelog/6231.improvement.rst index 1554a229b7f..aa622015a43 100644 --- a/changelog/6231.improvement.rst +++ b/changelog/6231.improvement.rst @@ -1 +1 @@ -Improve check for misspelling of ``pytest.mark.parametrize``. +Improve check for misspelling of :ref:`pytest.mark.parametrize ref`. diff --git a/changelog/6255.bugfix.rst b/changelog/6255.bugfix.rst index 831187feb84..46369787b2a 100644 --- a/changelog/6255.bugfix.rst +++ b/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. diff --git a/changelog/6257.improvement.rst b/changelog/6257.improvement.rst index a2155828600..71b7f56a3c5 100644 --- a/changelog/6257.improvement.rst +++ b/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. diff --git a/changelog/README.rst b/changelog/README.rst index 3e464508ac0..4635e5fa453 100644 --- a/changelog/README.rst +++ b/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``). diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index f9a219a92ae..88d31589830 100644 --- a/doc/en/changelog.rst +++ b/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 diff --git a/doc/en/conf.py b/doc/en/conf.py index 1e93f8e201f..7e8a2f2095d 100644 --- a/doc/en/conf.py +++ b/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) diff --git a/doc/en/reference.rst b/doc/en/reference.rst index b24ca5e5a12..693221bff5d 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -463,6 +463,8 @@ monkeypatch .. autoclass:: _pytest.monkeypatch.MonkeyPatch :members: +.. _testdir: + testdir ~~~~~~~ diff --git a/tox.ini b/tox.ini index 5e081725853..7e6a7ae2b2d 100644 --- a/tox.ini +++ b/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