Adjust doc links for new scheme

Closes #8831

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 ",
     )