Adjust doc links for new scheme

Closes #8831

CONTRIBUTING.rst

@@ -324,7 +324,7 @@ Here is a simple overview, with pytest-specific bits:
 Writing Tests
 ~~~~~~~~~~~~~
 
-Writing tests for plugins or for pytest itself is often done using the `pytester fixture <https://docs.pytest.org/en/stable/reference.html#pytester>`_, as a "black-box" test.
+Writing tests for plugins or for pytest itself is often done using the `pytester fixture <https://docs.pytest.org/en/stable/reference/reference.html#pytester>`_, as a "black-box" test.
 
 For example, to ensure a simple test passes you can write:
 

README.rst

@@ -79,17 +79,17 @@ Due to ``pytest``'s detailed assertion introspection, only plain ``assert`` stat
 Features
 --------
 
-- Detailed info on failing `assert statements <https://docs.pytest.org/en/stable/assert.html>`_ (no need to remember ``self.assert*`` names)
+- Detailed info on failing `assert statements <https://docs.pytest.org/en/stable/how-to/assert.html>`_ (no need to remember ``self.assert*`` names)
 
 - `Auto-discovery
-  <https://docs.pytest.org/en/stable/goodpractices.html#python-test-discovery>`_
+  <https://docs.pytest.org/en/stable/explanation/goodpractices.html#python-test-discovery>`_
   of test modules and functions
 
-- `Modular fixtures <https://docs.pytest.org/en/stable/fixture.html>`_ for
+- `Modular fixtures <https://docs.pytest.org/en/stable/explanation/fixtures.html>`_ for
   managing small or parametrized long-lived test resources
 
-- Can run `unittest <https://docs.pytest.org/en/stable/unittest.html>`_ (or trial),
+- Can run `unittest <https://docs.pytest.org/en/stable/how-to/unittest.html>`_ (or trial),
-  `nose <https://docs.pytest.org/en/stable/nose.html>`_ test suites out of the box
+  `nose <https://docs.pytest.org/en/stable/how-to/nose.html>`_ test suites out of the box
 
 - Python 3.6+ and PyPy3
 

doc/en/announce/release-2.0.0.rst

@@ -36,12 +36,12 @@ New Features
 
     import pytest ; pytest.main(arglist, pluginlist)
 
-  see http://pytest.org/en/stable/usage.html for details.
+  see http://pytest.org/en/stable/how-to/usage.html for details.
 
 - new and better reporting information in assert expressions
   if comparing lists, sequences or strings.
 
-  see http://pytest.org/en/stable/assert.html#newreport
+  see http://pytest.org/en/stable/how-to/assert.html#newreport
 
 - new configuration through ini-files (setup.cfg or tox.ini recognized),
   for example::
@@ -50,7 +50,7 @@ New Features
     norecursedirs = .hg data*  # don't ever recurse in such dirs
     addopts = -x --pyargs      # add these command line options by default
 
-  see http://pytest.org/en/stable/customize.html
+  see http://pytest.org/en/stable/reference/customize.html
 
 - improved standard unittest support.  In general py.test should now
   better be able to run custom unittest.TestCases like twisted trial

doc/en/announce/release-2.0.1.rst

@@ -57,7 +57,7 @@ Changes between 2.0.0 and 2.0.1
 - refinements to "collecting" output on non-ttys
 - refine internal plugin registration and --traceconfig output
 - introduce a mechanism to prevent/unregister plugins from the
-  command line, see http://pytest.org/en/stable/plugins.html#cmdunregister
+  command line, see http://pytest.org/en/stable/how-to/plugins.html#cmdunregister
 - activate resultlog plugin by default
 - fix regression wrt yielded tests which due to the
   collection-before-running semantics were not

doc/en/announce/release-2.1.0.rst

@@ -12,7 +12,7 @@ courtesy of Benjamin Peterson.  You can now safely use ``assert``
 statements in test modules without having to worry about side effects
 or python optimization ("-OO") options.  This is achieved by rewriting
 assert statements in test modules upon import, using a PEP302 hook.
-See https://docs.pytest.org/en/stable/assert.html for
+See https://docs.pytest.org/en/stable/how-to/assert.html for
 detailed information.  The work has been partly sponsored by my company,
 merlinux GmbH.
 

doc/en/announce/release-2.2.0.rst

@@ -9,7 +9,7 @@ with these improvements:
 
   - new @pytest.mark.parametrize decorator to run tests with different arguments
   - new metafunc.parametrize() API for parametrizing arguments independently
-  - see examples at http://pytest.org/en/stable/example/parametrize.html
+  - see examples at http://pytest.org/en/stable/example/how-to/parametrize.html
   - NOTE that parametrize() related APIs are still a bit experimental
     and might change in future releases.
 
@@ -78,7 +78,7 @@ Changes between 2.1.3 and 2.2.0
   or through plugin hooks.  Also introduce a "--strict" option which
   will treat unregistered markers as errors
   allowing to avoid typos and maintain a well described set of markers
-  for your test suite.  See examples at http://pytest.org/en/stable/mark.html
+  for your test suite.  See examples at http://pytest.org/en/stable/how-to/mark.html
   and its links.
 - issue50: introduce "-m marker" option to select tests based on markers
   (this is a stricter and more predictable version of "-k" in that "-m"

doc/en/announce/release-2.3.0.rst

@@ -13,12 +13,12 @@ re-usable fixture design.
 
 For detailed info and tutorial-style examples, see:
 
-    http://pytest.org/en/stable/fixture.html
+    http://pytest.org/en/stable/explanation/fixtures.html
 
 Moreover, there is now support for using pytest fixtures/funcargs with
 unittest-style suites, see here for examples:
 
-    http://pytest.org/en/stable/unittest.html
+    http://pytest.org/en/stable/how-to/unittest.html
 
 Besides, more unittest-test suites are now expected to "simply work"
 with pytest.

doc/en/announce/release-2.3.4.rst

@@ -16,7 +16,7 @@ comes with the following fixes and features:
 - yielded test functions will now have autouse-fixtures active but
   cannot accept fixtures as funcargs - it's anyway recommended to
   rather use the post-2.0 parametrize features instead of yield, see:
-  http://pytest.org/en/stable/example/parametrize.html
+  http://pytest.org/en/stable/example/how-to/parametrize.html
 - fix autouse-issue where autouse-fixtures would not be discovered
   if defined in an a/conftest.py file and tests in a/tests/test_some.py
 - fix issue226 - LIFO ordering for fixture teardowns

doc/en/announce/release-2.9.0.rst

@@ -131,7 +131,7 @@ The py.test Development Team
   with same name.
 
 
-.. _`traceback style docs`: https://pytest.org/en/stable/usage.html#modifying-python-traceback-printing
+.. _`traceback style docs`: https://pytest.org/en/stable/how-to/output.html#modifying-python-traceback-printing
 
 .. _#1422: https://github.com/pytest-dev/pytest/issues/1422
 .. _#1379: https://github.com/pytest-dev/pytest/issues/1379

doc/en/builtin.rst

@@ -144,7 +144,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
     recwarn
         Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
-        See https://docs.python.org/library/warnings.html for information
+        See https://docs.python.org/library/how-to/capture-warnings.html for information
         on warning categories.
 
     tmpdir_factory [session scope]

doc/en/changelog.rst

@@ -737,7 +737,7 @@ Features
           "integration",
       ]
 
-  More information can be found `in the docs <https://docs.pytest.org/en/stable/customize.html#configuration-file-formats>`__.
+  More information can be found `in the docs <https://docs.pytest.org/en/stable/reference/customize.html#configuration-file-formats>`__.
 
 
 - `#3342 <https://github.com/pytest-dev/pytest/issues/3342>`_: pytest now includes inline type annotations and exposes them to user programs.
@@ -785,7 +785,7 @@ Features
   We intend to make ``--import-mode=importlib`` the default in future versions, so users are encouraged
   to try the new mode and provide feedback (both positive or negative) in issue `#7245 <https://github.com/pytest-dev/pytest/issues/7245>`__.
 
-  You can read more about this option in `the documentation <https://docs.pytest.org/en/latest/pythonpath.html#import-modes>`__.
+  You can read more about this option in `the documentation <https://docs.pytest.org/en/latest/explanation/pythonpath.html#import-modes>`__.
 
 
 - `#7305 <https://github.com/pytest-dev/pytest/issues/7305>`_: New ``required_plugins`` configuration option allows the user to specify a list of plugins, including version information, that are required for pytest to run. An error is raised if any required plugins are not found when running pytest.
@@ -1677,7 +1677,7 @@ Features
 
 - `#1682 <https://github.com/pytest-dev/pytest/issues/1682>`_: The ``scope`` parameter of ``@pytest.fixture`` can now be a callable that receives
   the fixture name and the ``config`` object as keyword-only parameters.
-  See `the docs <https://docs.pytest.org/en/stable/fixture.html#dynamic-scope>`__ for more information.
+  See `the docs <https://docs.pytest.org/en/stable/how-to/fixtures.html#dynamic-scope>`__ for more information.
 
 
 - `#5764 <https://github.com/pytest-dev/pytest/issues/5764>`_: New behavior of the ``--pastebin`` option: failures to connect to the pastebin server are reported, without failing the pytest run
@@ -1816,7 +1816,7 @@ Features
 - `#5564 <https://github.com/pytest-dev/pytest/issues/5564>`_: New ``Config.invocation_args`` attribute containing the unchanged arguments passed to ``pytest.main()``.
 
 
-- `#5576 <https://github.com/pytest-dev/pytest/issues/5576>`_: New `NUMBER <https://docs.pytest.org/en/stable/doctest.html#using-doctest-options>`__
+- `#5576 <https://github.com/pytest-dev/pytest/issues/5576>`_: New `NUMBER <https://docs.pytest.org/en/stable/how-to/doctest.html#using-doctest-options>`__
   option for doctests to ignore irrelevant differences in floating-point numbers.
   Inspired by Sébastien Boisgérault's `numtest <https://github.com/boisgera/numtest>`__
   extension for doctest.
@@ -2013,7 +2013,7 @@ Deprecations
 Features
 --------
 
-- `#3457 <https://github.com/pytest-dev/pytest/issues/3457>`_: New `pytest_assertion_pass <https://docs.pytest.org/en/stable/reference.html#_pytest.hookspec.pytest_assertion_pass>`__
+- `#3457 <https://github.com/pytest-dev/pytest/issues/3457>`_: New `pytest_assertion_pass <https://docs.pytest.org/en/stable/reference/reference.html#_pytest.hookspec.pytest_assertion_pass>`__
   hook, called with context information when an assertion *passes*.
 
   This hook is still **experimental** so use it with caution.
@@ -2026,7 +2026,7 @@ Features
   `pytest-faulthandler <https://github.com/pytest-dev/pytest-faulthandler>`__ plugin into the core,
   so users should remove that plugin from their requirements if used.
 
-  For more information see the docs: https://docs.pytest.org/en/stable/usage.html#fault-handler
+  For more information see the docs: https://docs.pytest.org/en/stable/how-to/failures.html#fault-handler
 
 
 - `#5452 <https://github.com/pytest-dev/pytest/issues/5452>`_: When warnings are configured as errors, pytest warnings now appear as originating from ``pytest.`` instead of the internal ``_pytest.warning_types.`` module.
@@ -2423,7 +2423,7 @@ Features
 
   The existing ``--strict`` option has the same behavior currently, but can be augmented in the future for additional checks.
 
-  .. _`markers option`: https://docs.pytest.org/en/stable/reference.html#confval-markers
+  .. _`markers option`: https://docs.pytest.org/en/stable/reference/reference.html#confval-markers
 
 
 - `#5026 <https://github.com/pytest-dev/pytest/issues/5026>`_: Assertion failure messages for sequences and dicts contain the number of different items now.
@@ -2480,7 +2480,7 @@ Features
 
       CRITICAL root:test_log_cli_enabled_disabled.py:3 critical message logged by test
 
-  The formatting can be changed through the `log_format <https://docs.pytest.org/en/stable/reference.html#confval-log_format>`__ configuration option.
+  The formatting can be changed through the `log_format <https://docs.pytest.org/en/stable/reference/reference.html#confval-log_format>`__ configuration option.
 
 
 - `#5220 <https://github.com/pytest-dev/pytest/issues/5220>`_: ``--fixtures`` now also shows fixture scope for scopes other than ``"function"``.
@@ -2616,7 +2616,7 @@ Features
   .. _pdb++: https://pypi.org/project/pdbpp/
 
 
-- `#4875 <https://github.com/pytest-dev/pytest/issues/4875>`_: The `testpaths <https://docs.pytest.org/en/stable/reference.html#confval-testpaths>`__ configuration option is now displayed next
+- `#4875 <https://github.com/pytest-dev/pytest/issues/4875>`_: The `testpaths <https://docs.pytest.org/en/stable/reference/reference.html#confval-testpaths>`__ configuration option is now displayed next
   to the ``rootdir`` and ``inifile`` lines in the pytest header if the option is in effect, i.e., directories or file names were
   not explicitly passed in the command line.
 
@@ -2871,7 +2871,7 @@ pytest 4.2.0 (2019-01-30)
 Features
 --------
 
-- `#3094 <https://github.com/pytest-dev/pytest/issues/3094>`_: `Classic xunit-style <https://docs.pytest.org/en/stable/xunit_setup.html>`__ functions and methods
+- `#3094 <https://github.com/pytest-dev/pytest/issues/3094>`_: `Classic xunit-style <https://docs.pytest.org/en/stable/how-to/xunit_setup.html>`__ functions and methods
   now obey the scope of *autouse* fixtures.
 
   This fixes a number of surprising issues like ``setup_method`` being called before session-scoped
@@ -3379,7 +3379,7 @@ Features
   existing ``pytest_enter_pdb`` hook.
 
 
-- `#4147 <https://github.com/pytest-dev/pytest/issues/4147>`_: Add ``--sw``, ``--stepwise`` as an alternative to ``--lf -x`` for stopping at the first failure, but starting the next test invocation from that test.  See `the documentation <https://docs.pytest.org/en/stable/cache.html#stepwise>`__ for more info.
+- `#4147 <https://github.com/pytest-dev/pytest/issues/4147>`_: Add ``--sw``, ``--stepwise`` as an alternative to ``--lf -x`` for stopping at the first failure, but starting the next test invocation from that test.  See `the documentation <https://docs.pytest.org/en/stable/how-to/cache.html#stepwise>`__ for more info.
 
 
 - `#4188 <https://github.com/pytest-dev/pytest/issues/4188>`_: Make ``--color`` emit colorful dots when not running in verbose mode. Earlier, it would only colorize the test-by-test output if ``--verbose`` was also passed.
@@ -3784,13 +3784,13 @@ Features
   the standard warnings filters to manage those warnings. This introduces ``PytestWarning``,
   ``PytestDeprecationWarning`` and ``RemovedInPytest4Warning`` warning types as part of the public API.
 
-  Consult `the documentation <https://docs.pytest.org/en/stable/warnings.html#internal-pytest-warnings>`__ for more info.
+  Consult `the documentation <https://docs.pytest.org/en/stable/how-to/capture-warnings.html#internal-pytest-warnings>`__ for more info.
 
 
 - `#2908 <https://github.com/pytest-dev/pytest/issues/2908>`_: ``DeprecationWarning`` and ``PendingDeprecationWarning`` are now shown by default if no other warning filter is
   configured. This makes pytest more compliant with
   `PEP-0506 <https://www.python.org/dev/peps/pep-0565/#recommended-filter-settings-for-test-runners>`_. See
-  `the docs <https://docs.pytest.org/en/stable/warnings.html#deprecationwarning-and-pendingdeprecationwarning>`_ for
+  `the docs <https://docs.pytest.org/en/stable/how-to/capture-warnings.html#deprecationwarning-and-pendingdeprecationwarning>`_ for
   more info.
 
 
@@ -4223,7 +4223,7 @@ Features
 
 - Support for Python 3.7's builtin ``breakpoint()`` method, see `Using the
   builtin breakpoint function
-  <https://docs.pytest.org/en/stable/usage.html#breakpoint-builtin>`_ for
+  <https://docs.pytest.org/en/stable/how-to/failures.html#using-the-builtin-breakpoint-function>`_ for
   details. (`#3180 <https://github.com/pytest-dev/pytest/issues/3180>`_)
 
 - ``monkeypatch`` now supports a ``context()`` function which acts as a context
@@ -4363,7 +4363,7 @@ Features
 
 - New ``--rootdir`` command-line option to override the rules for discovering
   the root directory. See `customize
-  <https://docs.pytest.org/en/stable/customize.html>`_ in the documentation for
+  <https://docs.pytest.org/en/stable/reference/customize.html>`_ in the documentation for
   details. (`#1642 <https://github.com/pytest-dev/pytest/issues/1642>`_)
 
 - Fixtures are now instantiated based on their scopes, with higher-scoped
@@ -4450,7 +4450,7 @@ Bug Fixes
 Improved Documentation
 ----------------------
 
-- Added a `reference <https://docs.pytest.org/en/stable/reference.html>`_ page
+- Added a `reference <https://docs.pytest.org/en/stable/reference/reference.html>`_ page
   to the docs. (`#1713 <https://github.com/pytest-dev/pytest/issues/1713>`_)
 
 
@@ -4610,9 +4610,9 @@ Features
   <https://github.com/pytest-dev/pytest/issues/2527>`_)
 
 - **Incompatible change**: after community feedback the `logging
-  <https://docs.pytest.org/en/stable/logging.html>`_ functionality has
+  <https://docs.pytest.org/en/stable/how-to/logging.html>`_ functionality has
   undergone some changes. Please consult the `logging documentation
-  <https://docs.pytest.org/en/stable/logging.html#incompatible-changes-in-pytest-3-4>`_
+  <https://docs.pytest.org/en/stable/how-to/logging.html#incompatible-changes-in-pytest-3-4>`_
   for details. (`#3013 <https://github.com/pytest-dev/pytest/issues/3013>`_)
 
 - Console output falls back to "classic" mode when capturing is disabled (``-s``),
@@ -4620,10 +4620,10 @@ Features
   <https://github.com/pytest-dev/pytest/issues/3038>`_)
 
 - New `pytest_runtest_logfinish
-  <https://docs.pytest.org/en/stable/reference.html#_pytest.hookspec.pytest_runtest_logfinish>`_
+  <https://docs.pytest.org/en/stable/reference/reference.html#_pytest.hookspec.pytest_runtest_logfinish>`_
   hook which is called when a test item has finished executing, analogous to
   `pytest_runtest_logstart
-  <https://docs.pytest.org/en/stable/reference.html#_pytest.hookspec.pytest_runtest_logstart>`_.
+  <https://docs.pytest.org/en/stable/reference/reference.html#_pytest.hookspec.pytest_runtest_logstart>`_.
   (`#3101 <https://github.com/pytest-dev/pytest/issues/3101>`_)
 
 - Improve performance when collecting tests using many fixtures. (`#3107
@@ -4865,7 +4865,7 @@ Features
   markers. Also, a ``caplog`` fixture is available that enables users to test
   the captured log during specific tests (similar to ``capsys`` for example).
   For more information, please see the `logging docs
-  <https://docs.pytest.org/en/stable/logging.html>`_. This feature was
+  <https://docs.pytest.org/en/stable/how-to/logging.html>`_. This feature was
   introduced by merging the popular `pytest-catchlog
   <https://pypi.org/project/pytest-catchlog/>`_ plugin, thanks to `Thomas Hisch
   <https://github.com/thisch>`_. Be advised that during the merging the
@@ -5161,7 +5161,7 @@ Deprecations and Removals
 
 - ``pytest.approx`` no longer supports ``>``, ``>=``, ``<`` and ``<=``
   operators to avoid surprising/inconsistent behavior. See `the approx docs
-  <https://docs.pytest.org/en/stable/reference.html#pytest-approx>`_ for more
+  <https://docs.pytest.org/en/stable/reference/reference.html#pytest-approx>`_ for more
   information. (`#2003 <https://github.com/pytest-dev/pytest/issues/2003>`_)
 
 - All old-style specific behavior in current classes in the pytest's API is
@@ -5213,7 +5213,7 @@ Features
 
 - Introduced ``@pytest.mark.filterwarnings`` mark which allows overwriting the
   warnings filter on a per test, class or module level. See the `docs
-  <https://docs.pytest.org/en/stable/warnings.html#pytest-mark-
+  <https://docs.pytest.org/en/stable/how-to/capture-warnings.html#pytest-mark-
   filterwarnings>`_ for more information. (`#2598 <https://github.com/pytest-
   dev/pytest/issues/2598>`_)
 
@@ -5443,7 +5443,7 @@ New Features
       [pytest]
       addopts = -p no:warnings
 
-    See the `warnings documentation page <https://docs.pytest.org/en/stable/warnings.html>`_ for more
+    See the `warnings documentation page <https://docs.pytest.org/en/stable/how-to/capture-warnings.html>`_ for more
     information.
 
   Thanks `@nicoddemus`_ for the PR.
@@ -6517,7 +6517,7 @@ time or change existing behaviors in order to make them less surprising/more use
 * Fix (`#1422`_): junit record_xml_property doesn't allow multiple records
   with same name.
 
-.. _`traceback style docs`: https://pytest.org/en/stable/usage.html#modifying-python-traceback-printing
+.. _`traceback style docs`: https://docs.pytest.org/en/stable/how-to/output.html#modifying-python-traceback-printing
 
 .. _#1609: https://github.com/pytest-dev/pytest/issues/1609
 .. _#1422: https://github.com/pytest-dev/pytest/issues/1422
@@ -7776,7 +7776,7 @@ Bug fixes:
 - yielded test functions will now have autouse-fixtures active but
   cannot accept fixtures as funcargs - it's anyway recommended to
   rather use the post-2.0 parametrize features instead of yield, see:
-  http://pytest.org/en/stable/example/parametrize.html
+  http://pytest.org/en/stable/example/how-to/parametrize.html
 - fix autouse-issue where autouse-fixtures would not be discovered
   if defined in an a/conftest.py file and tests in a/tests/test_some.py
 - fix issue226 - LIFO ordering for fixture teardowns
@@ -8022,7 +8022,7 @@ Bug fixes:
   or through plugin hooks.  Also introduce a "--strict" option which
   will treat unregistered markers as errors
   allowing to avoid typos and maintain a well described set of markers
-  for your test suite.  See exaples at http://pytest.org/en/stable/mark.html
+  for your test suite.  See exaples at http://pytest.org/en/stable/how-to/mark.html
   and its links.
 - issue50: introduce "-m marker" option to select tests based on markers
   (this is a stricter and more predictable version of '-k' in that "-m"
@@ -8205,7 +8205,7 @@ Bug fixes:
 - refinements to "collecting" output on non-ttys
 - refine internal plugin registration and --traceconfig output
 - introduce a mechanism to prevent/unregister plugins from the
-  command line, see http://pytest.org/en/stable/plugins.html#cmdunregister
+  command line, see http://pytest.org/en/stable/how-to/plugins.html#cmdunregister
 - activate resultlog plugin by default
 - fix regression wrt yielded tests which due to the
   collection-before-running semantics were not

doc/en/example/markers.rst

@@ -234,17 +234,17 @@ You can ask which markers exist for your test suite - the list includes our just
 
     @pytest.mark.slow: mark test as slow.
 
-    @pytest.mark.filterwarnings(warning): add a warning filter to the given test. see https://docs.pytest.org/en/stable/warnings.html#pytest-mark-filterwarnings
+    @pytest.mark.filterwarnings(warning): add a warning filter to the given test. see https://docs.pytest.org/en/stable/how-to/capture-warnings.html#pytest-mark-filterwarnings
 
     @pytest.mark.skip(reason=None): skip the given test function with an optional reason. Example: skip(reason="no way of currently testing this") skips the test.
 
-    @pytest.mark.skipif(condition, ..., *, reason=...): skip the given test function if any of the conditions evaluate to True. Example: skipif(sys.platform == 'win32') skips the test if we are on the win32 platform. See https://docs.pytest.org/en/stable/reference.html#pytest-mark-skipif
+    @pytest.mark.skipif(condition, ..., *, reason=...): skip the given test function if any of the conditions evaluate to True. Example: skipif(sys.platform == 'win32') skips the test if we are on the win32 platform. See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-skipif
 
-    @pytest.mark.xfail(condition, ..., *, reason=..., run=True, raises=None, strict=xfail_strict): mark the test function as an expected failure if any of the conditions evaluate to True. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. If only specific exception(s) are expected, you can list them in raises, and if the test fails in other ways, it will be reported as a true failure. See https://docs.pytest.org/en/stable/reference.html#pytest-mark-xfail
+    @pytest.mark.xfail(condition, ..., *, reason=..., run=True, raises=None, strict=xfail_strict): mark the test function as an expected failure if any of the conditions evaluate to True. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. If only specific exception(s) are expected, you can list them in raises, and if the test fails in other ways, it will be reported as a true failure. See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-xfail
 
-    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in different arguments in turn. argvalues generally needs to be a list of values if argnames specifies only one name or a list of tuples of values if argnames specifies multiple names. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.see https://docs.pytest.org/en/stable/parametrize.html for more info and examples.
+    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in different arguments in turn. argvalues generally needs to be a list of values if argnames specifies only one name or a list of tuples of values if argnames specifies multiple names. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.see https://docs.pytest.org/en/stable/how-to/parametrize.html for more info and examples.
 
-    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/fixture.html#usefixtures
+    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/how-to/fixtures.html#usefixtures
 
     @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
 
@@ -428,17 +428,17 @@ The ``--markers`` option always gives you a list of available markers:
     $ pytest --markers
     @pytest.mark.env(name): mark test to run only on named environment
 
-    @pytest.mark.filterwarnings(warning): add a warning filter to the given test. see https://docs.pytest.org/en/stable/warnings.html#pytest-mark-filterwarnings
+    @pytest.mark.filterwarnings(warning): add a warning filter to the given test. see https://docs.pytest.org/en/stable/how-to/capture-warnings.html#pytest-mark-filterwarnings
 
     @pytest.mark.skip(reason=None): skip the given test function with an optional reason. Example: skip(reason="no way of currently testing this") skips the test.
 
-    @pytest.mark.skipif(condition, ..., *, reason=...): skip the given test function if any of the conditions evaluate to True. Example: skipif(sys.platform == 'win32') skips the test if we are on the win32 platform. See https://docs.pytest.org/en/stable/reference.html#pytest-mark-skipif
+    @pytest.mark.skipif(condition, ..., *, reason=...): skip the given test function if any of the conditions evaluate to True. Example: skipif(sys.platform == 'win32') skips the test if we are on the win32 platform. See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-skipif
 
-    @pytest.mark.xfail(condition, ..., *, reason=..., run=True, raises=None, strict=xfail_strict): mark the test function as an expected failure if any of the conditions evaluate to True. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. If only specific exception(s) are expected, you can list them in raises, and if the test fails in other ways, it will be reported as a true failure. See https://docs.pytest.org/en/stable/reference.html#pytest-mark-xfail
+    @pytest.mark.xfail(condition, ..., *, reason=..., run=True, raises=None, strict=xfail_strict): mark the test function as an expected failure if any of the conditions evaluate to True. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. If only specific exception(s) are expected, you can list them in raises, and if the test fails in other ways, it will be reported as a true failure. See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-xfail
 
-    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in different arguments in turn. argvalues generally needs to be a list of values if argnames specifies only one name or a list of tuples of values if argnames specifies multiple names. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.see https://docs.pytest.org/en/stable/parametrize.html for more info and examples.
+    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in different arguments in turn. argvalues generally needs to be a list of values if argnames specifies only one name or a list of tuples of values if argnames specifies multiple names. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.see https://docs.pytest.org/en/stable/how-to/parametrize.html for more info and examples.
 
-    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/fixture.html#usefixtures
+    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/explanation/fixtures.html#usefixtures
 
     @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
 

doc/en/explanation/flaky.rst

@@ -28,7 +28,7 @@ Flaky tests sometimes appear when a test suite is run in parallel (such as use o
 Overly strict assertion
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Overly strict assertions can cause problems with floating point comparison as well as timing issues. `pytest.approx <https://docs.pytest.org/en/stable/reference.html#pytest-approx>`_ is useful here.
+Overly strict assertions can cause problems with floating point comparison as well as timing issues. `pytest.approx <https://docs.pytest.org/en/stable/reference/reference.html#pytest-approx>`_ is useful here.
 
 
 Pytest features

doc/en/getting-started.rst

@@ -71,7 +71,7 @@ The ``[100%]`` refers to the overall progress of running all test cases. After i
 
 .. note::
 
-    You can use the ``assert`` statement to verify test expectations. pytest’s `Advanced assertion introspection <https://docs.python.org/reference/simple_stmts.html>`_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods <https://docs.python.org/library/unittest.html>`_.
+    You can use the ``assert`` statement to verify test expectations. pytest’s `Advanced assertion introspection <https://docs.python.org/reference/simple_stmts.html>`_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods <https://docs.python.org/library/how-to/unittest.html>`_.
 
 Run multiple tests
 ----------------------------------------------------------

doc/en/history.rst

@@ -121,7 +121,7 @@ project:
    -  Various `default
       plugins <http://web.archive.org/web/20091005181132/https://codespeak.net/py/dist/test/plugin/index.html>`__,
       including
-      `monkeypatch <http://web.archive.org/web/20091012022829/http://codespeak.net/py/dist/test/plugin/monkeypatch.html>`__
+      `monkeypatch <http://web.archive.org/web/20091012022829/http://codespeak.net/py/dist/test/plugin/how-to/monkeypatch.html>`__
 
 -  Even back there, the
    `FAQ <http://web.archive.org/web/20091005222413/http://codespeak.net/py/dist/faq.html>`__

doc/en/how-to/assert.rst

@@ -297,7 +297,7 @@ modules directly discovered by its test collection process, so **asserts in
 supporting modules which are not themselves test modules will not be rewritten**.
 
 You can manually enable assertion rewriting for an imported module by calling
-`register_assert_rewrite <https://docs.pytest.org/en/stable/writing_plugins.html#assertion-rewriting>`_
+`register_assert_rewrite <https://docs.pytest.org/en/stable/how-to/writing_plugins.html#assertion-rewriting>`_
 before you import it (a good place to do that is in your root ``conftest.py``).
 
 For further information, Benjamin Peterson wrote up `Behind the scenes of pytest's new assertion rewriting <http://pybites.blogspot.com/2011/07/behind-scenes-of-pytests-new-assertion.html>`_.

doc/en/how-to/capture-warnings.rst

@@ -40,7 +40,7 @@ Running pytest now produces this output:
       $REGENDOC_TMPDIR/test_show_warnings.py:5: UserWarning: api v1, should use functions from v2
         warnings.warn(UserWarning("api v1, should use functions from v2"))
 
-    -- Docs: https://docs.pytest.org/en/stable/warnings.html
+    -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
     ======================= 1 passed, 1 warning in 0.12s =======================
 
 The ``-W`` flag can be passed to control which warnings will be displayed or even turn
@@ -144,7 +144,7 @@ decorator or to all tests in a module by setting the :globalvar:`pytestmark` var
 *plugin.*
 
 .. _`-W option`: https://docs.python.org/3/using/cmdline.html#cmdoption-w
-.. _warnings.simplefilter: https://docs.python.org/3/library/warnings.html#warnings.simplefilter
+.. _warnings.simplefilter: https://docs.python.org/3/library/how-to/capture-warnings.html#warnings.simplefilter
 .. _`pytest-warnings`: https://github.com/fschulze/pytest-warnings
 
 Disabling warnings summary
@@ -398,7 +398,7 @@ defines an ``__init__`` constructor, as this prevents the class from being insta
       $REGENDOC_TMPDIR/test_pytest_warnings.py:1: PytestCollectionWarning: cannot collect test class 'Test' because it has a __init__ constructor (from: test_pytest_warnings.py)
         class Test:
 
-    -- Docs: https://docs.pytest.org/en/stable/warnings.html
+    -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
     1 warning in 0.12s
 
 These warnings might be filtered using the same builtin mechanisms used to filter other types of warnings.

doc/en/how-to/doctest.rst

@@ -95,7 +95,7 @@ that will be used for those doctest files using the
 Using 'doctest' options
 -----------------------
 
-Python's standard ``doctest`` module provides some `options <https://docs.python.org/3/library/doctest.html#option-flags>`__
+Python's standard ``doctest`` module provides some `options <https://docs.python.org/3/library/how-to/doctest.html#option-flags>`__
 to configure the strictness of doctest tests. In pytest, you can enable those flags using the
 configuration file.
 
@@ -252,7 +252,7 @@ For the same reasons one might want to skip normal tests, it is also possible to
 tests inside doctests.
 
 To skip a single check inside a doctest you can use the standard
-`doctest.SKIP <https://docs.python.org/3/library/doctest.html#doctest.SKIP>`__ directive:
+`doctest.SKIP <https://docs.python.org/3/library/how-to/doctest.html#doctest.SKIP>`__ directive:
 
 .. code-block:: python
 

doc/en/how-to/unittest.rst

@@ -27,8 +27,8 @@ Almost all ``unittest`` features are supported:
 * ``setUpClass/tearDownClass``;
 * ``setUpModule/tearDownModule``;
 
-.. _`load_tests protocol`: https://docs.python.org/3/library/unittest.html#load-tests-protocol
+.. _`load_tests protocol`: https://docs.python.org/3/library/how-to/unittest.html#load-tests-protocol
-.. _`subtests`: https://docs.python.org/3/library/unittest.html#distinguishing-test-iterations-using-subtests
+.. _`subtests`: https://docs.python.org/3/library/how-to/unittest.html#distinguishing-test-iterations-using-subtests
 
 Up to this point pytest does not have support for the following features:
 

doc/en/how-to/xunit_setup.rst

@@ -116,4 +116,4 @@ Remarks:
   Now the xunit-style functions are integrated with the fixture mechanism and obey the proper
   scope rules of fixtures involved in the call.
 
-.. _`unittest.py module`: https://docs.python.org/library/unittest.html
+.. _`unittest.py module`: https://docs.python.org/library/how-to/unittest.html

doc/en/projects.rst

@@ -56,7 +56,7 @@ Here are some examples of projects using ``pytest`` (please send notes via :ref:
 * `bu <https://packages.python.org/bu/>`_ a microscopic build system
 * `katcp <https://bitbucket.org/hodgestar/katcp>`_ Telescope communication protocol over Twisted
 * `kss plugin timer <https://pypi.org/project/kss.plugin.timer/>`_
-* `pyudev <https://pyudev.readthedocs.io/en/latest/tests/plugins.html>`_ a pure Python binding to the Linux library libudev
+* `pyudev <https://pyudev.readthedocs.io/en/latest/tests/how-to/plugins.html>`_ a pure Python binding to the Linux library libudev
 * `pytest-localserver <https://bitbucket.org/pytest-dev/pytest-localserver/>`_ a plugin for pytest that provides an httpserver and smtpserver
 * `pytest-monkeyplus <https://pypi.org/project/pytest-monkeyplus/>`_ a plugin that extends monkeypatch
 

doc/en/reference/reference.rst

@@ -118,7 +118,7 @@ Add warning filters to marked test items.
 
     :keyword str filter:
         A *warning specification string*, which is composed of contents of the tuple ``(action, message, category, module, lineno)``
-        as specified in `The Warnings filter <https://docs.python.org/3/library/warnings.html#warning-filter>`_ section of
+        as specified in `The Warnings filter <https://docs.python.org/3/library/how-to/capture-warnings.html#warning-filter>`_ section of
         the Python documentation, separated by ``":"``. Optional fields can be omitted.
         Module names passed for filtering are not regex-escaped.
 

src/_pytest/cacheprovider.py

@@ -43,7 +43,7 @@ which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
 
 **Do not** commit this to version control.
 
-See [the docs](https://docs.pytest.org/en/stable/cache.html) for more information.
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.
 """
 
 CACHEDIR_TAG_CONTENT = b"""\

src/_pytest/fixtures.py

@@ -1179,7 +1179,7 @@ def wrap_function_to_error_out_if_called_directly(
     message = (
         'Fixture "{name}" called directly. Fixtures are not meant to be called directly,\n'
         "but are created automatically when test functions request them as parameters.\n"
-        "See https://docs.pytest.org/en/stable/fixture.html for more information about fixtures, and\n"
+        "See https://docs.pytest.org/en/stable/explanation/fixtures.html for more information about fixtures, and\n"
         "https://docs.pytest.org/en/stable/deprecations.html#calling-fixtures-directly about how to update your code."
     ).format(name=fixture_marker.name or function.__name__)
 

src/_pytest/mark/structures.py

@@ -530,7 +530,7 @@ class MarkGenerator:
                 warnings.warn(
                     "Unknown pytest.mark.%s - is this a typo?  You can register "
                     "custom marks to avoid this warning - for details, see "
-                    "https://docs.pytest.org/en/stable/mark.html" % name,
+                    "https://docs.pytest.org/en/stable/how-to/mark.html" % name,
                     PytestUnknownMarkWarning,
                     2,
                 )

src/_pytest/outcomes.py

@@ -137,7 +137,7 @@ def skip(msg: str = "", *, allow_module_level: bool = False) -> "NoReturn":
         possible to declare a test to be skipped under certain conditions
         like mismatching platforms or dependencies.
         Similarly, use the ``# doctest: +SKIP`` directive (see `doctest.SKIP
-        <https://docs.python.org/3/library/doctest.html#doctest.SKIP>`_)
+        <https://docs.python.org/3/library/how-to/doctest.html#doctest.SKIP>`_)
         to skip a doctest statically.
     """
     __tracebackhide__ = True

src/_pytest/python.py

@@ -150,14 +150,14 @@ def pytest_configure(config: Config) -> None:
         "or a list of tuples of values if argnames specifies multiple names. "
         "Example: @parametrize('arg1', [1,2]) would lead to two calls of the "
         "decorated test function, one with arg1=1 and another with arg1=2."
-        "see https://docs.pytest.org/en/stable/parametrize.html for more info "
+        "see https://docs.pytest.org/en/stable/how-to/parametrize.html for more info "
         "and examples.",
     )
     config.addinivalue_line(
         "markers",
         "usefixtures(fixturename1, fixturename2, ...): mark tests as needing "
         "all of the specified fixtures. see "
-        "https://docs.pytest.org/en/stable/fixture.html#usefixtures ",
+        "https://docs.pytest.org/en/stable/explanation/fixtures.html#usefixtures ",
     )
 
 

src/_pytest/python_api.py

@@ -644,7 +644,7 @@ def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
       small numbers.  Also, it's only available in subclasses of ``unittest.TestCase``
       and it's ugly because it doesn't follow PEP8.  `More information...`__
 
-      __ https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertAlmostEqual
+      __ https://docs.python.org/3/library/how-to/unittest.html#unittest.TestCase.assertAlmostEqual
 
     - ``a == pytest.approx(b, rel=1e-6, abs=1e-12)``: True if the relative
       tolerance is met w.r.t. ``b`` or if the absolute tolerance is met.

src/_pytest/recwarn.py

@@ -29,7 +29,7 @@ T = TypeVar("T")
 def recwarn() -> Generator["WarningsRecorder", None, None]:
     """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
-    See https://docs.python.org/library/warnings.html for information
+    See https://docs.python.org/library/how-to/capture-warnings.html for information
     on warning categories.
     """
     wrec = WarningsRecorder(_ispytest=True)

src/_pytest/skipping.py

@@ -68,7 +68,7 @@ def pytest_configure(config: Config) -> None:
         "skipif(condition, ..., *, reason=...): "
         "skip the given test function if any of the conditions evaluate to True. "
         "Example: skipif(sys.platform == 'win32') skips the test if we are on the win32 platform. "
-        "See https://docs.pytest.org/en/stable/reference.html#pytest-mark-skipif",
+        "See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-skipif",
     )
     config.addinivalue_line(
         "markers",
@@ -78,7 +78,7 @@ def pytest_configure(config: Config) -> None:
         "and run=False if you don't even want to execute the test function. "
         "If only specific exception(s) are expected, you can list them in "
         "raises, and if the test fails in other ways, it will be reported as "
-        "a true failure. See https://docs.pytest.org/en/stable/reference.html#pytest-mark-xfail",
+        "a true failure. See https://docs.pytest.org/en/stable/reference/reference.html#pytest-mark-xfail",
     )
 
 

src/_pytest/terminal.py

@@ -958,7 +958,7 @@ class TerminalReporter:
                     message = message.rstrip()
                 self._tw.line(message)
                 self._tw.line()
-            self._tw.line("-- Docs: https://docs.pytest.org/en/stable/warnings.html")
+            self._tw.line("-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html")
 
     def summary_passes(self) -> None:
         if self.config.option.tbstyle != "no":

src/_pytest/warnings.py

@@ -21,7 +21,7 @@ def pytest_configure(config: Config) -> None:
     config.addinivalue_line(
         "markers",
         "filterwarnings(warning): add a warning filter to the given test. "
-        "see https://docs.pytest.org/en/stable/warnings.html#pytest-mark-filterwarnings ",
+        "see https://docs.pytest.org/en/stable/how-to/capture-warnings.html#pytest-mark-filterwarnings ",
     )
 
 

testing/test_pluginmanager.py

@@ -405,7 +405,7 @@ class TestPytestPluginManagerBootstrapming:
         self, pytestpm: PytestPluginManager
     ) -> None:
         """From PR #4304: The only way to unregister a module is documented at
-        the end of https://docs.pytest.org/en/stable/plugins.html.
+        the end of https://docs.pytest.org/en/stable/how-to/plugins.html.
 
         When unregister cacheprovider, then unregister stepwise too.
         """