From d1aea7d7a8f0fe70cf4e59fc7fd5f624a522da15 Mon Sep 17 00:00:00 2001 From: "oleg.hoefling" Date: Thu, 26 Aug 2021 16:05:03 +0200 Subject: [PATCH] use intersphinx crossrefs to stdlib docs where possible instead of hardcoded URLs Signed-off-by: oleg.hoefling --- doc/en/changelog.rst | 8 ++++---- doc/en/conf.py | 2 +- doc/en/explanation/goodpractices.rst | 4 +--- doc/en/explanation/pythonpath.rst | 6 +++--- doc/en/getting-started.rst | 2 +- doc/en/how-to/capture-warnings.rst | 8 +++----- doc/en/how-to/doctest.rst | 6 +++--- doc/en/how-to/failures.rst | 22 ++++++++++------------ doc/en/how-to/fixtures.rst | 6 +++--- doc/en/how-to/unittest.rst | 3 +-- doc/en/how-to/xunit_setup.rst | 2 -- doc/en/reference/customize.rst | 2 +- doc/en/reference/reference.rst | 8 ++------ 13 files changed, 33 insertions(+), 46 deletions(-) diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index 49c09eba0..2eb354e03 100644 --- a/doc/en/changelog.rst +++ b/doc/en/changelog.rst @@ -398,7 +398,7 @@ Improvements and should be preferred over them when possible. -- `#7780 `_: Public classes which are not designed to be inherited from are now marked `@final `_. +- `#7780 `_: Public classes which are not designed to be inherited from are now marked :func:`@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. @@ -772,7 +772,7 @@ Features - `#6906 `_: Added `--code-highlight` command line option to enable/disable code highlighting in terminal output. -- `#7245 `_: New ``--import-mode=importlib`` option that uses `importlib `__ to import test modules. +- `#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 @@ -2019,7 +2019,7 @@ Features This hook is still **experimental** so use it with caution. -- `#5440 `_: The `faulthandler `__ standard library +- `#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 @@ -3117,7 +3117,7 @@ Features will not issue the warning. -- `#3632 `_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs `__ or `dataclasses `_ (Python 3.7+, `backported to 3.6 `__). +- `#3632 `_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs `__ or :mod:`dataclasses` (Python 3.7+, `backported to 3.6 `__). - `#4278 `_: ``CACHEDIR.TAG`` files are now created inside cache directories. diff --git a/doc/en/conf.py b/doc/en/conf.py index ee71ffcae..70b9c93fe 100644 --- a/doc/en/conf.py +++ b/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), } diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index f66ef5a68..90765dd92 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/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 diff --git a/doc/en/explanation/pythonpath.rst b/doc/en/explanation/pythonpath.rst index 9aef44618..2330356b8 100644 --- a/doc/en/explanation/pythonpath.rst +++ b/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 `__. 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__ `__ 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 `__ 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. diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index bbe2a680e..1c777ebc5 100644 --- a/doc/en/getting-started.rst +++ b/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 `_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods `_. + You can use the ``assert`` statement to verify test expectations. pytest’s :ref:`Advanced assertion introspection ` will intelligently report intermediate values of the assert expression so you can avoid the many names :ref:`of JUnit legacy methods `. Run multiple tests ---------------------------------------------------------- diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index 188a7316d..14f8b3366 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/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 ` 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 `_ 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 `_ + by calling :func:`warnings.simplefilter` (see issue `#2430 `_ for an example of that). diff --git a/doc/en/how-to/doctest.rst b/doc/en/how-to/doctest.rst index c08ce5093..681c2037b 100644 --- a/doc/en/how-to/doctest.rst +++ b/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 `__ +Python's standard :mod:`doctest` module provides some :ref:`options ` 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 `__ directive: +:data:`doctest.SKIP` directive: .. code-block:: python diff --git a/doc/en/how-to/failures.rst b/doc/en/how-to/failures.rst index 0a0ec164d..ef8755091 100644 --- a/doc/en/how-to/failures.rst +++ b/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 ` 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 `. ``pytest`` +allows one to drop into the :doc:`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 ` 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 ` 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 `__ 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 diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 17efb0356..62b429ab0 100644 --- a/doc/en/how-to/fixtures.rst +++ b/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 -`_ 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 diff --git a/doc/en/how-to/unittest.rst b/doc/en/how-to/unittest.rst index 6f0d334b0..57b7d257f 100644 --- a/doc/en/how-to/unittest.rst +++ b/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 `; Benefits out of the box ----------------------- diff --git a/doc/en/how-to/xunit_setup.rst b/doc/en/how-to/xunit_setup.rst index 6d119299f..5a97b2c85 100644 --- a/doc/en/how-to/xunit_setup.rst +++ b/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 diff --git a/doc/en/reference/customize.rst b/doc/en/reference/customize.rst index 035d0f7ad..04845f935 100644 --- a/doc/en/reference/customize.rst +++ b/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 `__, and can also be used to hold pytest configuration +``setup.cfg`` files are general purpose configuration files, used originally by :doc:`distutils `, and can also be used to hold pytest configuration if they have a ``[tool:pytest]`` section. .. code-block:: ini diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 98b5a5064..7ff0bd043 100644 --- a/doc/en/reference/reference.rst +++ b/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 `_ 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 `, see :py:class:`_Result in the pluggy documentation ` 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