Merge pull request #9158 from hoefling/doc/internal-crossrefs

replace hardcoded urls to docs.pytest.org with internal crossrefs, add crossrefs to numpy docs, use sphinx pep role

doc/en/changelog.rst

@@ -295,7 +295,7 @@ Trivial/Internal Changes
 - `#7802 <https://github.com/pytest-dev/pytest/issues/7802>`_: The ``attrs`` dependency requirement is now >=19.2.0 instead of >=17.4.0.
 
 
-- `#8014 <https://github.com/pytest-dev/pytest/issues/8014>`_: `.pyc` files created by pytest's assertion rewriting now conform to the newer PEP-552 format on Python>=3.7.
+- `#8014 <https://github.com/pytest-dev/pytest/issues/8014>`_: `.pyc` files created by pytest's assertion rewriting now conform to the newer :pep:`552` format on Python>=3.7.
   (These files are internal and only interpreted by pytest itself.)
 
 
@@ -352,8 +352,7 @@ Breaking Changes
   * The ``--result-log`` option has been removed. Users are recommended to use the `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin instead.
 
 
-  For more information consult
+  For more information consult :std:doc:`deprecations` in the docs.
-  `Deprecations and Removals <https://docs.pytest.org/en/stable/deprecations.html>`__ in the docs.
 
 
 
@@ -544,8 +543,7 @@ Breaking Changes
   instead of warning messages.
 
   **The affected features will be effectively removed in pytest 6.1**, so please consult the
-  `Deprecations and Removals <https://docs.pytest.org/en/latest/deprecations.html>`__
+  :std:doc:`deprecations` section in the docs for directions on how to update existing code.
-  section in the docs for directions on how to update existing code.
 
   In the pytest ``6.0.X`` series, it is possible to change the errors back into warnings as a
   stopgap measure by adding this to your ``pytest.ini`` file:
@@ -750,7 +748,7 @@ Features
           "integration",
       ]
 
-  More information can be found `in the docs <https://docs.pytest.org/en/stable/reference/customize.html#configuration-file-formats>`__.
+  More information can be found :ref:`in the docs <config file formats>`.
 
 
 - `#3342 <https://github.com/pytest-dev/pytest/issues/3342>`_: pytest now includes inline type annotations and exposes them to user programs.
@@ -798,7 +796,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/explanation/pythonpath.html#import-modes>`__.
+  You can read more about this option in :std:ref:`the documentation <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.
@@ -1256,7 +1254,7 @@ Bug Fixes
 
 - `#6497 <https://github.com/pytest-dev/pytest/issues/6497>`_: Fix bug in the comparison of request key with cached key in fixture.
 
-  A construct ``if key == cached_key:`` can fail either because ``==`` is explicitly disallowed, or for, e.g., NumPy arrays, where the result of ``a == b`` cannot generally be converted to `bool`.
+  A construct ``if key == cached_key:`` can fail either because ``==`` is explicitly disallowed, or for, e.g., NumPy arrays, where the result of ``a == b`` cannot generally be converted to :class:`bool`.
   The implemented fix replaces `==` with ``is``.
 
 
@@ -1423,7 +1421,7 @@ Deprecations
   In order to smooth the transition, pytest will issue a warning in case the ``--junitxml`` option
   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/stable/deprecations.html#junit-family-default-value-change-to-xunit2>`__.
+  For more information, :ref:`see the docs <junit-family changed default value>`.
 
 
 
@@ -1690,7 +1688,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/how-to/fixtures.html#dynamic-scope>`__ for more information.
+  See :ref:`the docs <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
@@ -1794,8 +1792,7 @@ Removals
   * ``request`` is now a reserved name for fixtures.
 
 
-  For more information consult
+  For more information consult :std:doc:`deprecations` in the docs.
-  `Deprecations and Removals <https://docs.pytest.org/en/stable/deprecations.html>`__ in the docs.
 
 
 - `#5565 <https://github.com/pytest-dev/pytest/issues/5565>`_: Removed unused support code for `unittest2 <https://pypi.org/project/unittest2/>`__.
@@ -1829,7 +1826,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/how-to/doctest.html#using-doctest-options>`__
+- `#5576 <https://github.com/pytest-dev/pytest/issues/5576>`_: New :ref:`NUMBER <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.
@@ -1949,7 +1946,7 @@ Important
 
 This release is a Python3.5+ only release.
 
-For more details, see our `Python 2.7 and 3.4 support plan <https://docs.pytest.org/en/stable/py27-py34-deprecation.html>`__.
+For more details, see our :std:doc:`Python 2.7 and 3.4 support plan <py27-py34-deprecation>`.
 
 Removals
 --------
@@ -1970,8 +1967,7 @@ Removals
   instead of warning messages.
 
   **The affected features will be effectively removed in pytest 5.1**, so please consult the
-  `Deprecations and Removals <https://docs.pytest.org/en/stable/deprecations.html>`__
+  :std:doc:`deprecations` section in the docs for directions on how to update existing code.
-  section in the docs for directions on how to update existing code.
 
   In the pytest ``5.0.X`` series, it is possible to change the errors back into warnings as a stop
   gap measure by adding this to your ``pytest.ini`` file:
@@ -2026,7 +2022,7 @@ Deprecations
 Features
 --------
 
-- `#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>`__
+- `#3457 <https://github.com/pytest-dev/pytest/issues/3457>`_: New :func:`~_pytest.hookspec.pytest_assertion_pass`
   hook, called with context information when an assertion *passes*.
 
   This hook is still **experimental** so use it with caution.
@@ -2039,7 +2035,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/how-to/failures.html#fault-handler
+  For more information see the docs: :ref:`faulthandler`.
 
 
 - `#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.
@@ -2063,7 +2059,7 @@ Bug Fixes
   to avoid stale caches.
 
 
-- `#2761 <https://github.com/pytest-dev/pytest/issues/2761>`_: Honor PEP 235 on case-insensitive file systems.
+- `#2761 <https://github.com/pytest-dev/pytest/issues/2761>`_: Honor :pep:`235` on case-insensitive file systems.
 
 
 - `#5078 <https://github.com/pytest-dev/pytest/issues/5078>`_: Test module is no longer double-imported when using ``--pyargs``.
@@ -2174,7 +2170,7 @@ Features
 
 - `#6870 <https://github.com/pytest-dev/pytest/issues/6870>`_: New ``Config.invocation_args`` attribute containing the unchanged arguments passed to ``pytest.main()``.
 
-  Remark: while this is technically a new feature and according to our `policy <https://docs.pytest.org/en/latest/py27-py34-deprecation.html#what-goes-into-4-6-x-releases>`_ it should not have been backported, we have opened an exception in this particular case because it fixes a serious interaction with ``pytest-xdist``, so it can also be considered a bugfix.
+  Remark: while this is technically a new feature and according to our :ref:`policy <what goes into 4.6.x releases>` it should not have been backported, we have opened an exception in this particular case because it fixes a serious interaction with ``pytest-xdist``, so it can also be considered a bugfix.
 
 Trivial/Internal Changes
 ------------------------
@@ -2346,7 +2342,7 @@ Important
 
 The ``4.6.X`` series will be the last series to support **Python 2 and Python 3.4**.
 
-For more details, see our `Python 2.7 and 3.4 support plan <https://docs.pytest.org/en/stable/py27-py34-deprecation.html>`__.
+For more details, see our :std:doc:`Python 2.7 and 3.4 support plan <py27-py34-deprecation>`.
 
 
 Features
@@ -2432,12 +2428,10 @@ Features
 - `#5013 <https://github.com/pytest-dev/pytest/issues/5013>`_: Messages from crash reports are displayed within test summaries now, truncated to the terminal width.
 
 
-- `#5023 <https://github.com/pytest-dev/pytest/issues/5023>`_: New flag ``--strict-markers`` that triggers an error when unknown markers (e.g. those not registered using the `markers option`_ in the configuration file) are used in the test suite.
+- `#5023 <https://github.com/pytest-dev/pytest/issues/5023>`_: New flag ``--strict-markers`` that triggers an error when unknown markers (e.g. those not registered using the :confval:`markers` option in the configuration file) are used in the test suite.
 
   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/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.
 
@@ -2493,7 +2487,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/reference.html#confval-log_format>`__ configuration option.
+  The formatting can be changed through the :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"``.
@@ -2629,7 +2623,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/reference.html#confval-testpaths>`__ configuration option is now displayed next
+- `#4875 <https://github.com/pytest-dev/pytest/issues/4875>`_: The :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.
 
@@ -2884,7 +2878,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/how-to/xunit_setup.html>`__ functions and methods
+- `#3094 <https://github.com/pytest-dev/pytest/issues/3094>`_: :doc:`Classic xunit-style <how-to/xunit_setup>` 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
@@ -2950,7 +2944,7 @@ Trivial/Internal Changes
 
 - `#4643 <https://github.com/pytest-dev/pytest/issues/4643>`_: Use ``a.item()`` instead of the deprecated ``np.asscalar(a)`` in ``pytest.approx``.
 
-  ``np.asscalar`` has been `deprecated <https://github.com/numpy/numpy/blob/master/doc/release/1.16.0-notes.rst#new-deprecations>`__ in ``numpy 1.16.``.
+  ``np.asscalar`` has been :doc:`deprecated <numpy:release/1.16.0-notes>` in ``numpy 1.16.``.
 
 
 - `#4657 <https://github.com/pytest-dev/pytest/issues/4657>`_: Copy saferepr from pylib
@@ -3002,27 +2996,27 @@ Removals
 
 - `#3078 <https://github.com/pytest-dev/pytest/issues/3078>`_: Remove legacy internal warnings system: ``config.warn``, ``Node.warn``. The ``pytest_logwarning`` now issues a warning when implemented.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#config-warn-and-node-warn>`__ on information on how to update your code.
+  See our :ref:`docs <config.warn and node.warn deprecated>` on information on how to update your code.
 
 
 - `#3079 <https://github.com/pytest-dev/pytest/issues/3079>`_: Removed support for yield tests - they are fundamentally broken because they don't support fixtures properly since collection and test execution were separated.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#yield-tests>`__ on information on how to update your code.
+  See our :ref:`docs <yield tests deprecated>` on information on how to update your code.
 
 
 - `#3082 <https://github.com/pytest-dev/pytest/issues/3082>`_: Removed support for applying marks directly to values in ``@pytest.mark.parametrize``. Use ``pytest.param`` instead.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#marks-in-pytest-mark-parametrize>`__ on information on how to update your code.
+  See our :ref:`docs <marks in pytest.parametrize deprecated>` on information on how to update your code.
 
 
 - `#3083 <https://github.com/pytest-dev/pytest/issues/3083>`_: Removed ``Metafunc.addcall``. This was the predecessor mechanism to ``@pytest.mark.parametrize``.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#metafunc-addcall>`__ on information on how to update your code.
+  See our :ref:`docs <metafunc.addcall deprecated>` on information on how to update your code.
 
 
 - `#3085 <https://github.com/pytest-dev/pytest/issues/3085>`_: Removed support for passing strings to ``pytest.main``. Now, always pass a list of strings instead.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#passing-command-line-string-to-pytest-main>`__ on information on how to update your code.
+  See our :ref:`docs <passing command-line string to pytest.main deprecated>` on information on how to update your code.
 
 
 - `#3086 <https://github.com/pytest-dev/pytest/issues/3086>`_: ``[pytest]`` section in **setup.cfg** files is no longer supported, use ``[tool:pytest]`` instead. ``setup.cfg`` files
@@ -3033,17 +3027,17 @@ Removals
 
 - `#3616 <https://github.com/pytest-dev/pytest/issues/3616>`_: Removed the deprecated compat properties for ``node.Class/Function/Module`` - use ``pytest.Class/Function/Module`` now.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#internal-classes-accessed-through-node>`__ on information on how to update your code.
+  See our :ref:`docs <internal classes accessed through node deprecated>` on information on how to update your code.
 
 
 - `#4421 <https://github.com/pytest-dev/pytest/issues/4421>`_: Removed the implementation of the ``pytest_namespace`` hook.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#pytest-namespace>`__ on information on how to update your code.
+  See our :ref:`docs <pytest.namespace deprecated>` on information on how to update your code.
 
 
 - `#4489 <https://github.com/pytest-dev/pytest/issues/4489>`_: Removed ``request.cached_setup``. This was the predecessor mechanism to modern fixtures.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#cached-setup>`__ on information on how to update your code.
+  See our :ref:`docs <cached_setup deprecated>` on information on how to update your code.
 
 
 - `#4535 <https://github.com/pytest-dev/pytest/issues/4535>`_: Removed the deprecated ``PyCollector.makeitem`` method. This method was made public by mistake a long time ago.
@@ -3051,12 +3045,12 @@ Removals
 
 - `#4543 <https://github.com/pytest-dev/pytest/issues/4543>`_: Removed support to define fixtures using the ``pytest_funcarg__`` prefix. Use the ``@pytest.fixture`` decorator instead.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#pytest-funcarg-prefix>`__ on information on how to update your code.
+  See our :ref:`docs <pytest_funcarg__ prefix deprecated>` on information on how to update your code.
 
 
 - `#4545 <https://github.com/pytest-dev/pytest/issues/4545>`_: Calling fixtures directly is now always an error instead of a warning.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#calling-fixtures-directly>`__ on information on how to update your code.
+  See our :ref:`docs <calling fixtures directly deprecated>` on information on how to update your code.
 
 
 - `#4546 <https://github.com/pytest-dev/pytest/issues/4546>`_: Remove ``Node.get_marker(name)`` the return value was not usable for more than a existence check.
@@ -3066,12 +3060,12 @@ Removals
 
 - `#4547 <https://github.com/pytest-dev/pytest/issues/4547>`_: The deprecated ``record_xml_property`` fixture has been removed, use the more generic ``record_property`` instead.
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#record-xml-property>`__ for more information.
+  See our :ref:`docs <record_xml_property deprecated>` for more information.
 
 
 - `#4548 <https://github.com/pytest-dev/pytest/issues/4548>`_: An error is now raised if the ``pytest_plugins`` variable is defined in a non-top-level ``conftest.py`` file (i.e., not residing in the ``rootdir``).
 
-  See our `docs <https://docs.pytest.org/en/stable/deprecations.html#pytest-plugins-in-non-top-level-conftest-files>`__ for more information.
+  See our :ref:`docs <pytest_plugins in non-top-level conftest files deprecated>` for more information.
 
 
 - `#891 <https://github.com/pytest-dev/pytest/issues/891>`_: Remove ``testfunction.markername`` attributes - use ``Node.iter_markers(name=None)`` to iterate them.
@@ -3083,7 +3077,7 @@ Deprecations
 
 - `#3050 <https://github.com/pytest-dev/pytest/issues/3050>`_: Deprecated the ``pytest.config`` global.
 
-  See https://docs.pytest.org/en/stable/deprecations.html#pytest-config-global for rationale.
+  See :ref:`pytest.config global deprecated` for rationale.
 
 
 - `#3974 <https://github.com/pytest-dev/pytest/issues/3974>`_: Passing the ``message`` parameter of ``pytest.raises`` now issues a ``DeprecationWarning``.
@@ -3098,7 +3092,7 @@ Deprecations
 
 - `#4435 <https://github.com/pytest-dev/pytest/issues/4435>`_: Deprecated ``raises(..., 'code(as_a_string)')`` and ``warns(..., 'code(as_a_string)')``.
 
-  See https://docs.pytest.org/en/stable/deprecations.html#raises-warns-exec for rationale and examples.
+  See :std:ref:`raises-warns-exec` for rationale and examples.
 
 
 
@@ -3292,8 +3286,7 @@ Removals
   instead of warning messages.
 
   **The affected features will be effectively removed in pytest 4.1**, so please consult the
-  `Deprecations and Removals <https://docs.pytest.org/en/stable/deprecations.html>`__
+  :std:doc:`deprecations` section in the docs for directions on how to update existing code.
-  section in the docs for directions on how to update existing code.
 
   In the pytest ``4.0.X`` series, it is possible to change the errors back into warnings as a stop
   gap measure by adding this to your ``pytest.ini`` file:
@@ -3392,7 +3385,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/how-to/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 :ref:`the documentation <cache 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.
@@ -3544,7 +3537,7 @@ Deprecations
     Users should just ``import pytest`` and access those objects using the ``pytest`` module.
 
   * ``request.cached_setup``, this was the precursor of the setup/teardown mechanism available to fixtures. You can
-    consult `funcarg comparison section in the docs <https://docs.pytest.org/en/stable/funcarg_compare.html>`_.
+    consult :std:doc:`funcarg comparison section in the docs <funcarg_compare>`.
 
   * Using objects named ``"Class"`` as a way to customize the type of nodes that are collected in ``Collector``
     subclasses has been deprecated. Users instead should use ``pytest_collect_make_item`` to customize node types during
@@ -3757,7 +3750,7 @@ Bug Fixes
 Improved Documentation
 ----------------------
 
-- `#3996 <https://github.com/pytest-dev/pytest/issues/3996>`_: New `Deprecations and Removals <https://docs.pytest.org/en/stable/deprecations.html>`_ page shows all currently
+- `#3996 <https://github.com/pytest-dev/pytest/issues/3996>`_: New :std:doc:`deprecations` page shows all currently
   deprecated features, the rationale to do so, and alternatives to update your code. It also list features removed
   from pytest in past major releases to help those with ancient pytest versions to upgrade.
 
@@ -3779,7 +3772,7 @@ Deprecations and Removals
 -------------------------
 
 - `#2452 <https://github.com/pytest-dev/pytest/issues/2452>`_: ``Config.warn`` and ``Node.warn`` have been
-  deprecated, see `<https://docs.pytest.org/en/stable/deprecations.html#config-warn-and-node-warn>`_ for rationale and
+  deprecated, see :ref:`config.warn and node.warn deprecated` for rationale and
   examples.
 
 - `#3936 <https://github.com/pytest-dev/pytest/issues/3936>`_: ``@pytest.mark.filterwarnings`` second parameter is no longer regex-escaped,
@@ -3797,13 +3790,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/how-to/capture-warnings.html#internal-pytest-warnings>`__ for more info.
+  Consult :ref:`the documentation <internal-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
+  :pep:`506#recommended-filter-settings-for-test-runners`. See
-  `the docs <https://docs.pytest.org/en/stable/how-to/capture-warnings.html#deprecationwarning-and-pendingdeprecationwarning>`_ for
+  :ref:`the docs <deprecation-warnings>` for
   more info.
 
 
@@ -3997,10 +3990,10 @@ pytest 3.7.0 (2018-07-30)
 Deprecations and Removals
 -------------------------
 
-- `#2639 <https://github.com/pytest-dev/pytest/issues/2639>`_: ``pytest_namespace`` has been `deprecated <https://docs.pytest.org/en/stable/deprecations.html#pytest-namespace>`_.
+- `#2639 <https://github.com/pytest-dev/pytest/issues/2639>`_: ``pytest_namespace`` has been :ref:`deprecated <pytest.namespace deprecated>`.
 
 
-- `#3661 <https://github.com/pytest-dev/pytest/issues/3661>`_: Calling a fixture function directly, as opposed to request them in a test function, now issues a ``RemovedInPytest4Warning``. See `the documentation for rationale and examples <https://docs.pytest.org/en/stable/deprecations.html#calling-fixtures-directly>`_.
+- `#3661 <https://github.com/pytest-dev/pytest/issues/3661>`_: Calling a fixture function directly, as opposed to request them in a test function, now issues a ``RemovedInPytest4Warning``. See :ref:`the documentation for rationale and examples <calling fixtures directly deprecated>`.
 
 
 
@@ -4223,10 +4216,9 @@ Features
   node handling which fixes a number of long standing bugs caused by the old
   design. This introduces new ``Node.iter_markers(name)`` and
   ``Node.get_closest_marker(name)`` APIs. Users are **strongly encouraged** to
-  read the `reasons for the revamp in the docs
+  read the :ref:`reasons for the revamp in the docs <marker-revamp>`,
-  <https://docs.pytest.org/en/stable/historical-notes.html#marker-revamp-and-iteration>`_,
+  or jump over to details about :ref:`updating existing code to use the new APIs
-  or jump over to details about `updating existing code to use the new APIs
+  <update marker code>`.
-  <https://docs.pytest.org/en/stable/historical-notes.html#updating-code>`_.
   (`#3317 <https://github.com/pytest-dev/pytest/issues/3317>`_)
 
 - Now when ``@pytest.fixture`` is applied more than once to the same function a
@@ -4234,9 +4226,8 @@ Features
   and if was working for a test suite it was mostly by accident. (`#2334
   <https://github.com/pytest-dev/pytest/issues/2334>`_)
 
-- Support for Python 3.7's builtin ``breakpoint()`` method, see `Using the
+- Support for Python 3.7's builtin ``breakpoint()`` method, see
-  builtin breakpoint function
+  :ref:`Using the builtin breakpoint function <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
@@ -4362,8 +4353,9 @@ Deprecations and Removals
   <https://github.com/pytest-dev/pytest/issues/2770>`_)
 
 - Defining ``pytest_plugins`` is now deprecated in non-top-level conftest.py
-  files, because they "leak" to the entire directory tree. `See the docs <https://docs.pytest.org/en/stable/deprecations.html#pytest-plugins-in-non-top-level-conftest-files>`_ for the rationale behind this decision (`#3084
+  files, because they "leak" to the entire directory tree.
-  <https://github.com/pytest-dev/pytest/issues/3084>`_)
+  :ref:`See the docs <pytest_plugins in non-top-level conftest files deprecated>`
+  for the rationale behind this decision (`#3084 <https://github.com/pytest-dev/pytest/issues/3084>`_)
 
 
 Features
@@ -4375,8 +4367,7 @@ Features
   <https://github.com/pytest-dev/pytest/issues/1478>`_)
 
 - New ``--rootdir`` command-line option to override the rules for discovering
-  the root directory. See `customize
+  the root directory. See :doc:`customize <reference/customize>` 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
@@ -4463,7 +4454,7 @@ Bug Fixes
 Improved Documentation
 ----------------------
 
-- Added a `reference <https://docs.pytest.org/en/stable/reference/reference.html>`_ page
+- Added a :doc:`reference <reference/reference>` page
   to the docs. (`#1713 <https://github.com/pytest-dev/pytest/issues/1713>`_)
 
 
@@ -4622,21 +4613,17 @@ Features
   less error prone. (`#2527
   <https://github.com/pytest-dev/pytest/issues/2527>`_)
 
-- **Incompatible change**: after community feedback the `logging
+- **Incompatible change**: after community feedback the :doc:`logging <how-to/logging>` functionality has
-  <https://docs.pytest.org/en/stable/how-to/logging.html>`_ functionality has
+  undergone some changes. Please consult the :ref:`logging documentation <log_changes_3_4>`
-  undergone some changes. Please consult the `logging documentation
-  <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``),
   otherwise the output gets garbled to the point of being useless. (`#3038
   <https://github.com/pytest-dev/pytest/issues/3038>`_)
 
-- New `pytest_runtest_logfinish
+- New :func:`~_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
+  :func:`~_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
@@ -4877,8 +4864,7 @@ Features
   in ``pytest.ini``, the command line and also during individual tests using
   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
+  For more information, please see the :doc:`logging docs <how-to/logging>`. 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
@@ -5173,8 +5159,7 @@ Deprecations and Removals
 -------------------------
 
 - ``pytest.approx`` no longer supports ``>``, ``>=``, ``<`` and ``<=``
-  operators to avoid surprising/inconsistent behavior. See `the approx docs
+  operators to avoid surprising/inconsistent behavior. See the :func:`~pytest.approx` docs 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
@@ -5219,16 +5204,13 @@ Features
 
 - Introduce the ``PYTEST_CURRENT_TEST`` environment variable that is set with
   the ``nodeid`` and stage (``setup``, ``call`` and ``teardown``) of the test
-  being currently executed. See the `documentation
+  being currently executed. See the :ref:`documentation <pytest current test env>`
-  <https://docs.pytest.org/en/stable/example/simple.html#pytest-current-test-
+  for more info. (`#2583 <https://github.com/pytest-
-  environment-variable>`_ for more info. (`#2583 <https://github.com/pytest-
   dev/pytest/issues/2583>`_)
 
 - Introduced ``@pytest.mark.filterwarnings`` mark which allows overwriting the
-  warnings filter on a per test, class or module level. See the `docs
+  warnings filter on a per test, class or module level. See the :ref:`docs <filterwarnings>`
-  <https://docs.pytest.org/en/stable/how-to/capture-warnings.html#pytest-mark-
+  for more information. (`#2598 <https://github.com/pytest-dev/pytest/issues/2598>`_)
-  filterwarnings>`_ for more information. (`#2598 <https://github.com/pytest-
-  dev/pytest/issues/2598>`_)
 
 - ``--last-failed`` now remembers forever when a test has failed and only
   forgets it if it passes again. This makes it easy to fix a test suite by
@@ -5239,7 +5221,7 @@ Features
   messages to the terminal reporting after collection has been finished
   successfully. (`#2622 <https://github.com/pytest-dev/pytest/issues/2622>`_)
 
-- Added support for `PEP-415's <https://www.python.org/dev/peps/pep-0415/>`_
+- Added support for :pep:`415`\'s
   ``Exception.__suppress_context__``. Now if a ``raise exception from None`` is
   caught by pytest, pytest will no longer chain the context in the test report.
   The behavior now matches Python's traceback behavior. (`#2631
@@ -5456,7 +5438,7 @@ New Features
       [pytest]
       addopts = -p no:warnings
 
-    See the `warnings documentation page <https://docs.pytest.org/en/stable/how-to/capture-warnings.html>`_ for more
+    See the :doc:`warnings documentation page <how-to/capture-warnings>` for more
     information.
 
   Thanks `@nicoddemus`_ for the PR.
@@ -5625,7 +5607,7 @@ Bug Fixes
 * ``--override-ini`` now correctly overrides some fundamental options like ``python_files`` (`#2238`_).
   Thanks `@sirex`_ for the report and `@nicoddemus`_ for the PR.
 
-* Replace ``raise StopIteration`` usages in the code by simple ``returns`` to finish generators, in accordance to `PEP-479`_ (`#2160`_).
+* Replace ``raise StopIteration`` usages in the code by simple ``returns`` to finish generators, in accordance to :pep:`479` (`#2160`_).
   Thanks to `@nicoddemus`_ for the PR.
 
 * Fix internal errors when an unprintable ``AssertionError`` is raised inside a test.
@@ -5659,8 +5641,6 @@ Bug Fixes
 .. _#2238: https://github.com/pytest-dev/pytest/issues/2238
 .. _#2281: https://github.com/pytest-dev/pytest/issues/2281
 
-.. _PEP-479: https://www.python.org/dev/peps/pep-0479/
-
 
 3.0.6 (2017-01-22)
 ==================
@@ -5938,6 +5918,7 @@ Bug Fixes
 .. _#1832: https://github.com/pytest-dev/pytest/issues/1832
 .. _#1849: https://github.com/pytest-dev/pytest/issues/1849
 
+.. _release-3.0.0:
 
 3.0.0 (2016-08-18)
 ==================
@@ -6523,14 +6504,13 @@ time or change existing behaviors in order to make them less surprising/more use
 * Fix formatting utf-8 explanation messages (`#1379`_).
   Thanks `@biern`_ for the PR.
 
-* Fix `traceback style docs`_ to describe all of the available options
+* Fix :ref:`traceback style docs <how-to-modifying-python-tb-printing>` to describe all of the available options
   (auto/long/short/line/native/no), with ``auto`` being the default since v2.6.
   Thanks `@hackebrot`_ for the PR.
 
 * Fix (`#1422`_): junit record_xml_property doesn't allow multiple records
   with same name.
 
-.. _`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
@@ -6796,7 +6776,7 @@ time or change existing behaviors in order to make them less surprising/more use
   Thanks Bruno Oliveira for the PR.
 
 - fix issue808: pytest's internal assertion rewrite hook now implements the
-  optional PEP302 get_data API so tests can access data files next to them.
+  optional :pep:`302` get_data API so tests can access data files next to them.
   Thanks xmo-odoo for request and example and Bruno Oliveira for
   the PR.
 
@@ -7404,7 +7384,7 @@ time or change existing behaviors in order to make them less surprising/more use
 
 - close issue240 - document precisely how pytest module importing
   works, discuss the two common test directory layouts, and how it
-  interacts with PEP420-namespace packages.
+  interacts with :pep:`420`\-namespace packages.
 
 - fix issue246 fix finalizer order to be LIFO on independent fixtures
   depending on a parametrized higher-than-function scoped fixture.
@@ -7464,7 +7444,7 @@ time or change existing behaviors in order to make them less surprising/more use
   (it already did neutralize pytest.mark.xfail markers)
 
 - refine pytest / pkg_resources interactions: The AssertionRewritingHook
-  PEP302 compliant loader now registers itself with setuptools/pkg_resources
+  :pep:`302` compliant loader now registers itself with setuptools/pkg_resources
   properly so that the pkg_resources.resource_stream method works properly.
   Fixes issue366.  Thanks for the investigations and full PR to Jason R. Coombs.
 

doc/en/conf.py

@@ -123,7 +123,6 @@ pygments_style = "sphinx"
 # A list of regular expressions that match URIs that should not be checked when
 # doing a linkcheck.
 linkcheck_ignore = [
-    "https://github.com/numpy/numpy/blob/master/doc/release/1.16.0-notes.rst#new-deprecations",
     "https://blogs.msdn.microsoft.com/bharry/2017/06/28/testing-in-a-cloud-delivery-cadence/",
     "http://pythontesting.net/framework/pytest-introduction/",
     r"https://github.com/pytest-dev/pytest/issues/\d+",
@@ -350,6 +349,7 @@ texinfo_documents = [
 intersphinx_mapping = {
     "pluggy": ("https://pluggy.readthedocs.io/en/stable", None),
     "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
 }
 
 

doc/en/deprecations.rst

@@ -171,6 +171,7 @@ A ``--show-capture`` command-line option was added in ``pytest 3.5.0`` which all
 display captured output when tests fail: ``no``, ``stdout``, ``stderr``, ``log`` or ``all`` (the default).
 
 
+.. _resultlog deprecated:
 
 Result log (``--result-log``)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -208,6 +209,8 @@ with ``py.io.TerminalWriter``.
 Plugins that used ``TerminalReporter.writer`` directly should instead use ``TerminalReporter``
 methods that provide the same functionality.
 
+.. _junit-family changed default value:
+
 ``junit_family`` default value change to "xunit2"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -295,6 +298,8 @@ in places where we or plugin authors must distinguish between fixture names and
 names supplied by non-fixture things such as ``pytest.mark.parametrize``.
 
 
+.. _pytest.config global deprecated:
+
 ``pytest.config`` global
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -392,6 +397,8 @@ This issue should affect only advanced plugins who create new collection types,
 message please contact the authors so they can change the code.
 
 
+.. _marks in pytest.parametrize deprecated:
+
 marks in ``pytest.mark.parametrize``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -440,6 +447,8 @@ To update the code, use ``pytest.param``:
         ...
 
 
+.. _pytest_funcarg__ prefix deprecated:
+
 ``pytest_funcarg__`` prefix
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -471,6 +480,8 @@ Switch over to the ``@pytest.fixture`` decorator:
 to avoid conflicts with other distutils commands.
 
 
+.. _metafunc.addcall deprecated:
+
 Metafunc.addcall
 ~~~~~~~~~~~~~~~~
 
@@ -495,6 +506,8 @@ Becomes:
         metafunc.parametrize("i", [1, 2], ids=["1", "2"])
 
 
+.. _cached_setup deprecated:
+
 ``cached_setup``
 ~~~~~~~~~~~~~~~~
 
@@ -523,10 +536,12 @@ This should be updated to make use of standard fixture mechanisms:
         session.close()
 
 
-You can consult `funcarg comparison section in the docs <https://docs.pytest.org/en/stable/funcarg_compare.html>`_ for
+You can consult :std:doc:`funcarg comparison section in the docs <funcarg_compare>` for
 more information.
 
 
+.. _pytest_plugins in non-top-level conftest files deprecated:
+
 pytest_plugins in non-top-level conftest files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -537,6 +552,8 @@ files because they will activate referenced plugins *globally*, which is surpris
 features ``conftest.py`` files are only *active* for tests at or below it.
 
 
+.. _config.warn and node.warn deprecated:
+
 ``Config.warn`` and ``Node.warn``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -564,6 +581,8 @@ Becomes:
 
 * ``node.warn("CI", "some message")``: this code/message form has been **removed** and should be converted to the warning instance form above.
 
+.. _record_xml_property deprecated:
+
 record_xml_property
 ~~~~~~~~~~~~~~~~~~~
 
@@ -587,6 +606,8 @@ Change to:
         ...
 
 
+.. _passing command-line string to pytest.main deprecated:
+
 Passing command-line string to ``pytest.main()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -609,6 +630,8 @@ By passing a string, users expect that pytest will interpret that command-line u
 on (for example ``bash`` or ``Powershell``), but this is very hard/impossible to do in a portable way.
 
 
+.. _calling fixtures directly deprecated:
+
 Calling fixtures directly
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -662,6 +685,8 @@ with the ``name`` parameter:
         return cell()
 
 
+.. _yield tests deprecated:
+
 ``yield`` tests
 ~~~~~~~~~~~~~~~
 
@@ -690,6 +715,8 @@ This form of test function doesn't support fixtures properly, and users should s
     def test_squared(x, y):
         assert x ** x == y
 
+.. _internal classes accessed through node deprecated:
+
 Internal classes accessed through ``Node``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -724,6 +751,8 @@ As part of a large :ref:`marker-revamp` we already deprecated using ``MarkInfo``
 the only correct way to get markers of an element is via ``node.iter_markers(name)``.
 
 
+.. _pytest.namespace deprecated:
+
 ``pytest_namespace``
 ~~~~~~~~~~~~~~~~~~~~
 

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/reference.html#pytest-approx>`_ is useful here.
+Overly strict assertions can cause problems with floating point comparison as well as timing issues. :func:`pytest.approx` is useful here.
 
 
 Pytest features

doc/en/funcarg_compare.rst

@@ -7,7 +7,7 @@ pytest-2.3: reasoning for fixture/funcarg evolution
 
 **Target audience**: Reading this document requires basic knowledge of
 python testing, xUnit setup methods and the (previous) basic pytest
-funcarg mechanism, see https://docs.pytest.org/en/stable/historical-notes.html#funcargs-and-pytest-funcarg.
+funcarg mechanism, see :ref:`historical funcargs and pytest.funcargs`.
 If you are new to pytest, then you can simply ignore this
 section and read the other sections.
 

doc/en/getting-started.rst

@@ -203,7 +203,7 @@ Note that attributes added at class level are *class attributes*, so they will b
 Request a unique temporary directory for functional tests
 --------------------------------------------------------------
 
-``pytest`` provides `Builtin fixtures/function arguments <https://docs.pytest.org/en/stable/builtin.html>`_ to request arbitrary resources, like a unique temporary directory:
+``pytest`` provides :std:doc:`Builtin fixtures/function arguments <builtin>` to request arbitrary resources, like a unique temporary directory:
 
 .. code-block:: python
 

doc/en/historical-notes.rst

@@ -125,6 +125,7 @@ as a third party plugin named ``pytest-cache``.  The core plugin
 is compatible regarding command line options and API usage except that you
 can only store/receive data between test runs that is json-serializable.
 
+.. _historical funcargs and pytest.funcargs:
 
 funcargs and ``pytest_funcarg__``
 ---------------------------------

doc/en/history.rst

@@ -136,8 +136,7 @@ project:
    released <https://mail.python.org/pipermail/pytest-dev/2010-November/001687.html>`__
    as a package separate from ``py`` (but still called ``py.test``).
 
--  In August 2016, pytest 3.0.0 `was
+-  In August 2016, pytest 3.0.0 :std:ref:`was released <release-3.0.0>`,
-   released <https://docs.pytest.org/en/latest/changelog.html#id1313>`__,
    which adds ``pytest`` (rather than ``py.test``) as the recommended
    command-line entry point
 

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/how-to/writing_plugins.html#assertion-rewriting>`_
+:ref:`register_assert_rewrite <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/cache.rst

@@ -325,6 +325,8 @@ servers where isolation and correctness is more important
 than speed.
 
 
+.. _cache stepwise:
+
 Stepwise
 --------
 

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

@@ -172,7 +172,7 @@ DeprecationWarning and PendingDeprecationWarning
 
 
 By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning`` warnings from
-user code and third-party libraries, as recommended by `PEP-0565 <https://www.python.org/dev/peps/pep-0565>`_.
+user code and third-party libraries, as recommended by :pep:`565`.
 This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed.
 
 Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over
@@ -197,7 +197,7 @@ the regular expression ``".*U.*mode is deprecated"``.
     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
+    Also pytest doesn't follow :pep:`506` suggestion of resetting all warning filters because
     it might break test suites that configure warning filters themselves
     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

@@ -92,6 +92,8 @@ that will be used for those doctest files using the
     [pytest]
     doctest_encoding = latin1
 
+.. _using doctest options:
+
 Using 'doctest' options
 -----------------------
 

doc/en/how-to/output.rst

@@ -3,6 +3,8 @@
 Managing pytest's output
 =========================
 
+.. _how-to-modifying-python-tb-printing:
+
 Modifying Python traceback printing
 --------------------------------------------------
 
@@ -465,8 +467,7 @@ by the `PyPy-test`_ web page to show test results over several revisions.
 
     If you use this option, consider using the new `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin instead.
 
-    See `the deprecation docs <https://docs.pytest.org/en/stable/deprecations.html#result-log-result-log>`__
+    See :ref:`the deprecation docs <resultlog deprecated>` for more information.
-    for more information.
 
 
 .. _`PyPy-test`: http://buildbot.pypy.org/summary

doc/en/how-to/unittest.rst

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

doc/en/py27-py34-deprecation.rst

@@ -8,10 +8,10 @@ features only made possible on newer Python versions.
 In case of Python 2 and 3, the difference between the languages makes it even more prominent,
 because many new Python 3 features cannot be used in a Python 2/3 compatible code base.
 
-Python 2.7 EOL has been reached `in 2020 <https://legacy.python.org/dev/peps/pep-0373/#id4>`__, with
+Python 2.7 EOL has been reached :pep:`in 2020 <0373#maintenance-releases>`, with
 the last release made in April, 2020.
 
-Python 3.4 EOL has been reached `in 2019 <https://www.python.org/dev/peps/pep-0429/#release-schedule>`__, with the last release made in March, 2019.
+Python 3.4 EOL has been reached :pep:`in 2019 <0429#release-schedule>`, with the last release made in March, 2019.
 
 For those reasons, in Jun 2019 it was decided that **pytest 4.6** series will be the last to support Python 2.7 and 3.4.
 
@@ -47,6 +47,8 @@ Technical aspects
 
 In this section we describe the technical aspects of the Python 2.7 and 3.4 support plan.
 
+.. _what goes into 4.6.x releases:
+
 What goes into 4.6.X releases
 +++++++++++++++++++++++++++++
 

src/_pytest/outcomes.py

@@ -136,8 +136,7 @@ def skip(msg: str = "", *, allow_module_level: bool = False) -> "NoReturn":
         It is better to use the :ref:`pytest.mark.skipif ref` marker when
         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
+        Similarly, use the ``# doctest: +SKIP`` directive (see :py:data:`doctest.SKIP`)
-        <https://docs.python.org/3/library/how-to/doctest.html#doctest.SKIP>`_)
         to skip a doctest statically.
     """
     __tracebackhide__ = True

src/_pytest/python_api.py

@@ -518,14 +518,12 @@ def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
     """Assert that two numbers (or two sets of numbers) are equal to each other
     within some tolerance.
 
-    Due to the `intricacies of floating-point arithmetic`__, numbers that we
+    Due to the :std:doc:`tutorial/floatingpoint`, numbers that we
     would intuitively expect to be equal are not always so::
 
         >>> 0.1 + 0.2 == 0.3
         False
 
-    __ https://docs.python.org/3/tutorial/floatingpoint.html
-
     This problem is commonly encountered when writing tests, e.g. when making
     sure that floating-point values are what you expect them to be.  One way to
     deal with this problem is to assert that two floating-point numbers are
@@ -630,26 +628,22 @@ def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
       both ``a`` and ``b``, this test is symmetric (i.e.  neither ``a`` nor
       ``b`` is a "reference value").  You have to specify an absolute tolerance
       if you want to compare to ``0.0`` because there is no tolerance by
-      default.  `More information...`__
+      default.  More information: :py:func:`math.isclose`.
-
-      __ https://docs.python.org/3/library/math.html#math.isclose
 
     - ``numpy.isclose(a, b, rtol=1e-5, atol=1e-8)``: True if the difference
       between ``a`` and ``b`` is less that the sum of the relative tolerance
       w.r.t. ``b`` and the absolute tolerance.  Because the relative tolerance
       is only calculated w.r.t. ``b``, this test is asymmetric and you can
       think of ``b`` as the reference value.  Support for comparing sequences
-      is provided by ``numpy.allclose``.  `More information...`__
+      is provided by :py:func:`numpy.allclose`.  More information:
-
+      :std:doc:`numpy:reference/generated/numpy.isclose`.
-      __ https://numpy.org/doc/stable/reference/generated/numpy.isclose.html
 
     - ``unittest.TestCase.assertAlmostEqual(a, b)``: True if ``a`` and ``b``
       are within an absolute tolerance of ``1e-7``.  No relative tolerance is
       considered , so this function is not appropriate for very large or very
       small numbers.  Also, it's only available in subclasses of ``unittest.TestCase``
-      and it's ugly because it doesn't follow PEP8.  `More information...`__
+      and it's ugly because it doesn't follow PEP8.  More information:
-
+      :py:meth:`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.
@@ -661,16 +655,14 @@ def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
     .. note::
 
         ``approx`` can handle numpy arrays, but we recommend the
-        specialised test helpers in `numpy.testing`__ if you need
+        specialised test helpers in :std:doc:`numpy:reference/routines.testing`
-        support for comparisons, NaNs, or ULP-based tolerances.
+        if you need support for comparisons, NaNs, or ULP-based tolerances.
-
-        __ https://numpy.org/doc/stable/reference/routines.testing.html
 
     .. warning::
 
        .. versionchanged:: 3.2
 
-       In order to avoid inconsistent behavior, ``TypeError`` is
+       In order to avoid inconsistent behavior, :py:exc:`TypeError` is
        raised for ``>``, ``>=``, ``<`` and ``<=`` comparisons.
        The example below illustrates the problem::
 
@@ -680,9 +672,7 @@ def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
        In the second example one expects ``approx(0.1).__le__(0.1 + 1e-10)``
        to be called. But instead, ``approx(0.1).__lt__(0.1 + 1e-10)`` is used to
        comparison. This is because the call hierarchy of rich comparisons
-       follows a fixed behavior. `More information...`__
+       follows a fixed behavior. More information: :py:meth:`object.__ge__`
-
-       __ https://docs.python.org/3/reference/datamodel.html#object.__ge__
 
     .. versionchanged:: 3.7.1
        ``approx`` raises ``TypeError`` when it encounters a dict value or
@@ -790,17 +780,15 @@ def raises(
     :kwparam match:
         If specified, a string containing a regular expression,
         or a regular expression object, that is tested against the string
-        representation of the exception using ``re.search``. To match a literal
+        representation of the exception using :py:func:`re.search`. To match a literal
-        string that may contain `special characters`__, the pattern can
+        string that may contain :std:ref:`special characters <re-syntax>`, the pattern can
-        first be escaped with ``re.escape``.
+        first be escaped with :py:func:`re.escape`.
 
-        (This is only used when ``pytest.raises`` is used as a context manager,
+        (This is only used when :py:func:`pytest.raises` is used as a context manager,
         and passed through to the function otherwise.
-        When using ``pytest.raises`` as a function, you can use:
+        When using :py:func:`pytest.raises` as a function, you can use:
         ``pytest.raises(Exc, func, match="passed on").match("my pattern")``.)
 
-        __ https://docs.python.org/3/library/re.html#regular-expression-syntax
-
     .. currentmodule:: _pytest._code
 
     Use ``pytest.raises`` as a context manager, which will capture the exception of the given