Merge pull request #9041 from hoefling/doc/stdlib-crossrefs

doc/en/changelog.rst

@@ -411,7 +411,7 @@ Improvements
   and should be preferred over them when possible.
 
 
-- `#7780 <https://github.com/pytest-dev/pytest/issues/7780>`_: Public classes which are not designed to be inherited from are now marked `@final <https://docs.python.org/3/library/typing.html#typing.final>`_.
+- `#7780 <https://github.com/pytest-dev/pytest/issues/7780>`_: Public classes which are not designed to be inherited from are now marked :func:`@final <typing.final>`.
   Code which inherits from these classes will trigger a type-checking (e.g. mypy) error, but will still work in runtime.
   Currently the ``final`` designation does not appear in the API Reference but hopefully will in the future.
 
@@ -785,7 +785,7 @@ Features
 - `#6906 <https://github.com/pytest-dev/pytest/issues/6906>`_: Added `--code-highlight` command line option to enable/disable code highlighting in terminal output.
 
 
-- `#7245 <https://github.com/pytest-dev/pytest/issues/7245>`_: New ``--import-mode=importlib`` option that uses `importlib <https://docs.python.org/3/library/importlib.html>`__ to import test modules.
+- `#7245 <https://github.com/pytest-dev/pytest/issues/7245>`_: New ``--import-mode=importlib`` option that uses :mod:`importlib` to import test modules.
 
   Traditionally pytest used ``__import__`` while changing ``sys.path`` to import test modules (which
   also changes ``sys.modules`` as a side-effect), which works but has a number of drawbacks, like requiring test modules
@@ -2032,7 +2032,7 @@ Features
   This hook is still **experimental** so use it with caution.
 
 
-- `#5440 <https://github.com/pytest-dev/pytest/issues/5440>`_: The `faulthandler <https://docs.python.org/3/library/faulthandler.html>`__ standard library
+- `#5440 <https://github.com/pytest-dev/pytest/issues/5440>`_: The :mod:`faulthandler` standard library
   module is now enabled by default to help users diagnose crashes in C modules.
 
   This functionality was provided by integrating the external
@@ -3130,7 +3130,7 @@ Features
   will not issue the warning.
 
 
-- `#3632 <https://github.com/pytest-dev/pytest/issues/3632>`_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs <https://www.attrs.org/en/stable/>`__ or `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_ (Python 3.7+, `backported to 3.6 <https://pypi.org/project/dataclasses>`__).
+- `#3632 <https://github.com/pytest-dev/pytest/issues/3632>`_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs <https://www.attrs.org/en/stable/>`__ or :mod:`dataclasses` (Python 3.7+, `backported to 3.6 <https://pypi.org/project/dataclasses>`__).
 
 
 - `#4278 <https://github.com/pytest-dev/pytest/issues/4278>`_: ``CACHEDIR.TAG`` files are now created inside cache directories.

doc/en/conf.py

@@ -348,7 +348,7 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    "pluggy": ("https://pluggy.readthedocs.io/en/latest", None),
+    "pluggy": ("https://pluggy.readthedocs.io/en/stable", None),
     "python": ("https://docs.python.org/3", None),
 }
 

doc/en/explanation/goodpractices.rst

@@ -7,7 +7,7 @@ Good Integration Practices
 Install package with pip
 -------------------------------------------------
 
-For development, we recommend you use venv_ for virtual environments and
+For development, we recommend you use :mod:`venv` for virtual environments and
 pip_ for installing your application and any dependencies,
 as well as the ``pytest`` package itself.
 This ensures your code and dependencies are isolated from your system Python installation.
@@ -248,5 +248,3 @@ dependencies and then executing a pre-configured test command with
 options.  It will run tests against the installed package and not
 against your source code checkout, helping to detect packaging
 glitches.
-
-.. _`venv`: https://docs.python.org/3/library/venv.html

doc/en/explanation/pythonpath.rst

@@ -11,12 +11,12 @@ Import modes
 pytest as a testing framework needs to import test modules and ``conftest.py`` files for execution.
 
 Importing files in Python (at least until recently) is a non-trivial processes, often requiring
-changing `sys.path <https://docs.python.org/3/library/sys.html#sys.path>`__. Some aspects of the
+changing :data:`sys.path`. Some aspects of the
 import process can be controlled through the ``--import-mode`` command-line flag, which can assume
 these values:
 
 * ``prepend`` (default): the directory path containing each module will be inserted into the *beginning*
-  of :py:data:`sys.path` if not already there, and then imported with the `__import__ <https://docs.python.org/3/library/functions.html#__import__>`__ builtin.
+  of :py:data:`sys.path` if not already there, and then imported with the :func:`__import__ <__import__>` builtin.
 
   This requires test module names to be unique when the test directory tree is not arranged in
   packages, because the modules will put in :py:data:`sys.modules` after importing.
@@ -43,7 +43,7 @@ these values:
   Same as ``prepend``, requires test module names to be unique when the test directory tree is
   not arranged in packages, because the modules will put in :py:data:`sys.modules` after importing.
 
-* ``importlib``: new in pytest-6.0, this mode uses `importlib <https://docs.python.org/3/library/importlib.html>`__ to import test modules. This gives full control over the import process, and doesn't require changing :py:data:`sys.path`.
+* ``importlib``: new in pytest-6.0, this mode uses :mod:`importlib` to import test modules. This gives full control over the import process, and doesn't require changing :py:data:`sys.path`.
 
   For this reason this doesn't require test module names to be unique, but also makes test
   modules non-importable by each other.

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/how-to/unittest.html>`_.
+    You can use the ``assert`` statement to verify test expectations. pytest’s :ref:`Advanced assertion introspection <python:assert>` will intelligently report intermediate values of the assert expression so you can avoid the many names :ref:`of JUnit legacy methods <testcase-objects>`.
 
 Run multiple tests
 ----------------------------------------------------------

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

@@ -98,7 +98,7 @@ When a warning matches more than one option in the list, the action for the last
 is performed.
 
 Both ``-W`` command-line option and ``filterwarnings`` ini option are based on Python's own
-`-W option`_ and `warnings.simplefilter`_, so please refer to those sections in the Python
+:option:`-W option <python:-W>` and :func:`warnings.simplefilter`, so please refer to those sections in the Python
 documentation for other examples and advanced usage.
 
 .. _`filterwarnings`:
@@ -143,8 +143,6 @@ decorator or to all tests in a module by setting the :globalvar:`pytestmark` var
 *Credits go to Florian Schulze for the reference implementation in the* `pytest-warnings`_
 *plugin.*
 
-.. _`-W option`: https://docs.python.org/3/using/cmdline.html#cmdoption-w
-.. _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
@@ -196,12 +194,12 @@ the regular expression ``".*U.*mode is deprecated"``.
 .. note::
 
     If warnings are configured at the interpreter level, using
-    the `PYTHONWARNINGS <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS>`_ environment variable or the
+    the :envvar:`python:PYTHONWARNINGS` environment variable or the
     ``-W`` command-line option, pytest will not configure any filters by default.
 
     Also pytest doesn't follow ``PEP-0506`` suggestion of resetting all warning filters because
     it might break test suites that configure warning filters themselves
-    by calling ``warnings.simplefilter`` (see issue `#2430 <https://github.com/pytest-dev/pytest/issues/2430>`_
+    by calling :func:`warnings.simplefilter` (see issue `#2430 <https://github.com/pytest-dev/pytest/issues/2430>`_
     for an example of that).
 
 

doc/en/how-to/doctest.rst

@@ -4,7 +4,7 @@ How to run doctests
 =========================================================
 
 By default, all files matching the ``test*.txt`` pattern will
-be run through the python standard ``doctest`` module.  You
+be run through the python standard :mod:`doctest` module.  You
 can change the pattern by issuing:
 
 .. code-block:: bash
@@ -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/how-to/doctest.html#option-flags>`__
+Python's standard :mod:`doctest` module provides some :ref:`options <python:option-flags-and-directives>`
 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/how-to/doctest.html#doctest.SKIP>`__ directive:
+:data:`doctest.SKIP` directive:
 
 .. code-block:: python
 

doc/en/how-to/failures.rst

@@ -18,16 +18,14 @@ To stop the testing process after the first (N) failures:
 
 .. _pdb-option:
 
-Using PDB_ (Python Debugger) with pytest
-----------------------------------------------------------
+Using :doc:`python:library/pdb` with pytest
+-------------------------------------------
 
-Dropping to PDB_ (Python Debugger) on failures
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dropping to :doc:`pdb <python:library/pdb>` on failures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. _PDB: https://docs.python.org/library/pdb.html
-
-Python comes with a builtin Python debugger called PDB_.  ``pytest``
-allows one to drop into the PDB_ prompt via a command line option:
+Python comes with a builtin Python debugger called :doc:`pdb <python:library/pdb>`.  ``pytest``
+allows one to drop into the :doc:`pdb <python:library/pdb>` prompt via a command line option:
 
 .. code-block:: bash
 
@@ -57,10 +55,10 @@ for example::
 
 .. _trace-option:
 
-Dropping to PDB_ at the start of a test
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dropping to :doc:`pdb <python:library/pdb>` at the start of a test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:
+``pytest`` allows one to drop into the :doc:`pdb <python:library/pdb>` prompt immediately at the start of each test via a command line option:
 
 .. code-block:: bash
 
@@ -106,7 +104,7 @@ Fault Handler
 
 .. versionadded:: 5.0
 
-The `faulthandler <https://docs.python.org/3/library/faulthandler.html>`__ standard module
+The :mod:`faulthandler` standard module
 can be used to dump Python tracebacks on a segfault or after a timeout.
 
 The module is automatically enabled for pytest runs, unless the ``-p no:faulthandler`` is given

doc/en/how-to/fixtures.rst

@@ -1577,9 +1577,9 @@ Use fixtures in classes and modules with ``usefixtures``
 Sometimes test functions do not directly need access to a fixture object.
 For example, tests may require to operate with an empty directory as the
 current working directory but otherwise do not care for the concrete
-directory.  Here is how you can use the standard `tempfile
-<https://docs.python.org/library/tempfile.html>`_ and pytest fixtures to
-achieve it.  We separate the creation of the fixture into a conftest.py
+directory.  Here is how you can use the standard :mod:`tempfile`
+and pytest fixtures to
+achieve it.  We separate the creation of the fixture into a :file:`conftest.py`
 file:
 
 .. code-block:: python

doc/en/how-to/unittest.rst

@@ -28,12 +28,11 @@ Almost all ``unittest`` features are supported:
 * ``setUpModule/tearDownModule``;
 
 .. _`load_tests protocol`: https://docs.python.org/3/library/how-to/unittest.html#load-tests-protocol
-.. _`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:
 
 * `load_tests protocol`_;
-* `subtests`_;
+* :ref:`subtests <python:subtests>`;
 
 Benefits out of the box
 -----------------------

doc/en/how-to/xunit_setup.rst

@@ -115,5 +115,3 @@ 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/how-to/unittest.html

doc/en/reference/customize.rst

@@ -89,7 +89,7 @@ and can also be used to hold pytest configuration if they have a ``[pytest]`` se
 setup.cfg
 ~~~~~~~~~
 
-``setup.cfg`` files are general purpose configuration files, used originally by `distutils <https://docs.python.org/3/distutils/configfile.html>`__, and can also be used to hold pytest configuration
+``setup.cfg`` files are general purpose configuration files, used originally by :doc:`distutils <distutils/configfile>`, and can also be used to hold pytest configuration
 if they have a ``[tool:pytest]`` section.
 
 .. code-block:: ini

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/how-to/capture-warnings.html#warning-filter>`_ section of
+        as specified in :ref:`python:warning-filter` section of
         the Python documentation, separated by ``":"``. Optional fields can be omitted.
         Module names passed for filtering are not regex-escaped.
 
@@ -958,7 +958,6 @@ _Result
 
 Result object used within :ref:`hook wrappers <hookwrapper>`, see :py:class:`_Result in the pluggy documentation <pluggy._callers._Result>` for more information.
 
-
 Stash
 ~~~~~
 
@@ -1266,7 +1265,7 @@ passed multiple times. The expected format is ``name=value``. For example::
 .. confval:: faulthandler_timeout
 
    Dumps the tracebacks of all threads if a test takes longer than ``X`` seconds to run (including
-   fixture setup and teardown). Implemented using the `faulthandler.dump_traceback_later`_ function,
+   fixture setup and teardown). Implemented using the :func:`faulthandler.dump_traceback_later` function,
    so all caveats there apply.
 
    .. code-block:: ini
@@ -1277,9 +1276,6 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    For more information please refer to :ref:`faulthandler`.
 
-.. _`faulthandler.dump_traceback_later`: https://docs.python.org/3/library/faulthandler.html#faulthandler.dump_traceback_later
-
-
 .. confval:: filterwarnings