Merge pull request #9401 from bluetech/doc-hooks-ref

doc: add a `hook` crossref type

Author: bluetech

doc/en/changelog.rst

@@ -156,7 +156,7 @@ Deprecations
   See :ref:`the deprecation note <diamond-inheritance-deprecated>` for full details.
 
 
-- `#8592 <https://github.com/pytest-dev/pytest/issues/8592>`_: :func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` has been officially deprecated.  It will be removed in a future release.  Use :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` instead.
+- `#8592 <https://github.com/pytest-dev/pytest/issues/8592>`_: :hook:`pytest_cmdline_preparse` has been officially deprecated.  It will be removed in a future release.  Use :hook:`pytest_load_initial_conftests` instead.
 
   See :ref:`the deprecation note <cmdline-preparse-deprecated>` for full details.
 
@@ -203,11 +203,11 @@ Features
   - ``pytest.Mark`` for :class:`marks <pytest.Mark>`.
   - ``pytest.MarkDecorator`` for :class:`mark decorators <pytest.MarkDecorator>`.
   - ``pytest.MarkGenerator`` for the :class:`pytest.mark <pytest.MarkGenerator>` singleton.
-  - ``pytest.Metafunc`` for the :class:`metafunc <pytest.MarkGenerator>` argument to the :func:`pytest_generate_tests <pytest.hookspec.pytest_generate_tests>` hook.
+  - ``pytest.Metafunc`` for the :class:`metafunc <pytest.MarkGenerator>` argument to the :hook:`pytest_generate_tests` hook.
   - ``pytest.CallInfo`` for the :class:`CallInfo <pytest.CallInfo>` type passed to various hooks.
   - ``pytest.PytestPluginManager`` for :class:`PytestPluginManager <pytest.PytestPluginManager>`.
   - ``pytest.ExceptionInfo`` for the :class:`ExceptionInfo <pytest.ExceptionInfo>` type returned from :func:`pytest.raises` and passed to various hooks.
-  - ``pytest.Parser`` for the :class:`Parser <pytest.Parser>` type passed to the :func:`pytest_addoption <pytest.hookspec.pytest_addoption>` hook.
+  - ``pytest.Parser`` for the :class:`Parser <pytest.Parser>` type passed to the :hook:`pytest_addoption` hook.
   - ``pytest.OptionGroup`` for the :class:`OptionGroup <pytest.OptionGroup>` type returned from the :func:`parser.addgroup <pytest.Parser.getgroup>` method.
   - ``pytest.HookRecorder`` for the :class:`HookRecorder <pytest.HookRecorder>` type returned from :class:`~pytest.Pytester`.
   - ``pytest.RecordedHookCall`` for the :class:`RecordedHookCall <pytest.HookRecorder>` type returned from :class:`~pytest.HookRecorder`.
@@ -228,11 +228,11 @@ Features
 
 - `#8144 <https://github.com/pytest-dev/pytest/issues/8144>`_: The following hooks now receive an additional ``pathlib.Path`` argument, equivalent to an existing ``py.path.local`` argument:
 
-  - :func:`pytest_ignore_collect <_pytest.hookspec.pytest_ignore_collect>` - The ``collection_path`` parameter (equivalent to existing ``path`` parameter).
-  - :func:`pytest_collect_file <_pytest.hookspec.pytest_collect_file>` - The ``file_path`` parameter (equivalent to existing ``path`` parameter).
-  - :func:`pytest_pycollect_makemodule <_pytest.hookspec.pytest_pycollect_makemodule>` - The ``module_path`` parameter (equivalent to existing ``path`` parameter).
-  - :func:`pytest_report_header <_pytest.hookspec.pytest_report_header>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter).
-  - :func:`pytest_report_collectionfinish <_pytest.hookspec.pytest_report_collectionfinish>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter).
+  - :hook:`pytest_ignore_collect` - The ``collection_path`` parameter (equivalent to existing ``path`` parameter).
+  - :hook:`pytest_collect_file` - The ``file_path`` parameter (equivalent to existing ``path`` parameter).
+  - :hook:`pytest_pycollect_makemodule` - The ``module_path`` parameter (equivalent to existing ``path`` parameter).
+  - :hook:`pytest_report_header` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter).
+  - :hook:`pytest_report_collectionfinish` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter).
 
   .. note::
       The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the
@@ -491,7 +491,7 @@ Trivial/Internal Changes
 - `#8913 <https://github.com/pytest-dev/pytest/issues/8913>`_: The private ``CallSpec2._arg2scopenum`` attribute has been removed after an internal refactoring.
 
 
-- `#8967 <https://github.com/pytest-dev/pytest/issues/8967>`_: :func:`pytest_assertion_pass <_pytest.hookspec.pytest_assertion_pass>` is no longer considered experimental and
+- `#8967 <https://github.com/pytest-dev/pytest/issues/8967>`_: :hook:`pytest_assertion_pass` is no longer considered experimental and
   future changes to it will be considered more carefully.
 
 
@@ -853,8 +853,8 @@ Deprecations
   if you use this and want a replacement.
 
 
-- :issue:`7255`: The :func:`pytest_warning_captured <_pytest.hookspec.pytest_warning_captured>` hook is deprecated in favor
-  of :func:`pytest_warning_recorded <_pytest.hookspec.pytest_warning_recorded>`, and will be removed in a future version.
+- :issue:`7255`: The :hook:`pytest_warning_captured` hook is deprecated in favor
+  of :hook:`pytest_warning_recorded`, and will be removed in a future version.
 
 
 - :issue:`7648`: The ``gethookproxy()`` and ``isinitpath()`` methods of ``FSCollector`` and ``Package`` are deprecated;
@@ -962,7 +962,7 @@ Trivial/Internal Changes
   process, pytest now ignores builtin attributes (like ``__class__``,
   ``__delattr__`` and ``__new__``) without consulting the :confval:`python_classes` and
   :confval:`python_functions` configuration options and without passing them to plugins
-  using the :func:`pytest_pycollect_makeitem <_pytest.hookspec.pytest_pycollect_makeitem>` hook.
+  using the :hook:`pytest_pycollect_makeitem` hook.
 
 
 pytest 6.0.2 (2020-09-04)
@@ -1751,7 +1751,7 @@ Bug Fixes
 - :issue:`6646`: Assertion rewriting hooks are (re)stored for the current item, which fixes them being still used after e.g. pytester's :func:`testdir.runpytest <_pytest.pytester.Testdir.runpytest>` etc.
 
 
-- :issue:`6660`: :py:func:`pytest.exit` is handled when emitted from the :func:`pytest_sessionfinish <_pytest.hookspec.pytest_sessionfinish>` hook.  This includes quitting from a debugger.
+- :issue:`6660`: :py:func:`pytest.exit` is handled when emitted from the :hook:`pytest_sessionfinish` hook.  This includes quitting from a debugger.
 
 
 - :issue:`6752`: When :py:func:`pytest.raises` is used as a function (as opposed to a context manager),
@@ -1863,7 +1863,7 @@ Improvements
 - :issue:`6231`: Improve check for misspelling of :ref:`pytest.mark.parametrize ref`.
 
 
-- :issue:`6257`: Handle :py:func:`pytest.exit` being used via :py:func:`~_pytest.hookspec.pytest_internalerror`, e.g. when quitting pdb from post mortem.
+- :issue:`6257`: Handle :func:`pytest.exit` being used via :hook:`pytest_internalerror`, e.g. when quitting pdb from post mortem.
 
 
 
@@ -2497,7 +2497,7 @@ Deprecations
 Features
 --------
 
-- :issue:`3457`: New :func:`~_pytest.hookspec.pytest_assertion_pass`
+- :issue:`3457`: New :hook:`pytest_assertion_pass`
   hook, called with context information when an assertion *passes*.
 
   This hook is still **experimental** so use it with caution.
@@ -5017,9 +5017,9 @@ Features
 - Console output falls back to "classic" mode when capturing is disabled (``-s``),
   otherwise the output gets garbled to the point of being useless. (:issue:`3038`)
 
-- New :func:`~_pytest.hookspec.pytest_runtest_logfinish`
+- New :hook:`pytest_runtest_logfinish`
   hook which is called when a test item has finished executing, analogous to
-  :func:`~_pytest.hookspec.pytest_runtest_logstart`.
+  :hook:`pytest_runtest_logstart`.
   (:issue:`3101`)
 
 - Improve performance when collecting tests using many fixtures. (:issue:`3107`)

doc/en/conf.py

@@ -445,6 +445,13 @@ def setup(app: "sphinx.application.Sphinx") -> None:
         indextemplate="pair: %s; global variable interpreted by pytest",
     )
 
+    app.add_crossref_type(
+        directivename="hook",
+        rolename="hook",
+        objname="pytest hook",
+        indextemplate="pair: %s; hook",
+    )
+
     configure_logging(app)
 
     # Make Sphinx mark classes with "final" when decorated with @final.

doc/en/deprecations.rst

@@ -81,11 +81,11 @@ no matter what argument was used in the constructor. We expect to deprecate the
 
 In order to support the transition from ``py.path.local`` to :mod:`pathlib`, the following hooks now receive additional arguments:
 
-*  :func:`pytest_ignore_collect(collection_path: pathlib.Path) <_pytest.hookspec.pytest_ignore_collect>` as equivalent to ``path``
-*  :func:`pytest_collect_file(file_path: pathlib.Path) <_pytest.hookspec.pytest_collect_file>` as equivalent to ``path``
-*  :func:`pytest_pycollect_makemodule(module_path: pathlib.Path) <_pytest.hookspec.pytest_pycollect_makemodule>` as equivalent to ``path``
-*  :func:`pytest_report_header(start_path: pathlib.Path) <_pytest.hookspec.pytest_report_header>` as equivalent to ``startdir``
-*  :func:`pytest_report_collectionfinish(start_path: pathlib.Path) <_pytest.hookspec.pytest_report_collectionfinish>` as equivalent to ``startdir``
+*  :hook:`pytest_ignore_collect(collection_path: pathlib.Path) <pytest_ignore_collect>` as equivalent to ``path``
+*  :hook:`pytest_collect_file(file_path: pathlib.Path) <pytest_collect_file>` as equivalent to ``path``
+*  :hook:`pytest_pycollect_makemodule(module_path: pathlib.Path) <pytest_pycollect_makemodule>` as equivalent to ``path``
+*  :hook:`pytest_report_header(start_path: pathlib.Path) <pytest_report_header>` as equivalent to ``startdir``
+*  :hook:`pytest_report_collectionfinish(start_path: pathlib.Path) <pytest_report_collectionfinish>` as equivalent to ``startdir``
 
 The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments.
 
@@ -157,8 +157,8 @@ Implementing the ``pytest_cmdline_preparse`` hook
 
 .. deprecated:: 7.0
 
-Implementing the :func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` hook has been officially deprecated.
-Implement the :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` hook instead.
+Implementing the :hook:`pytest_cmdline_preparse` hook has been officially deprecated.
+Implement the :hook:`pytest_load_initial_conftests` hook instead.
 
 .. code-block:: python
 
@@ -331,8 +331,8 @@ at some point, depending on the plans for the plugins and number of users using
 
 .. versionremoved:: 6.0
 
-The ``pytest_collect_directory`` has not worked properly for years (it was called
-but the results were ignored). Users may consider using :func:`pytest_collection_modifyitems <_pytest.hookspec.pytest_collection_modifyitems>` instead.
+The ``pytest_collect_directory`` hook has not worked properly for years (it was called
+but the results were ignored). Users may consider using :hook:`pytest_collection_modifyitems` instead.
 
 TerminalReporter.writer
 ~~~~~~~~~~~~~~~~~~~~~~~

doc/en/reference/reference.rst

@@ -671,9 +671,13 @@ Bootstrapping hooks
 
 Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
 
+.. hook:: pytest_load_initial_conftests
 .. autofunction:: pytest_load_initial_conftests
+.. hook:: pytest_cmdline_preparse
 .. autofunction:: pytest_cmdline_preparse
+.. hook:: pytest_cmdline_parse
 .. autofunction:: pytest_cmdline_parse
+.. hook:: pytest_cmdline_main
 .. autofunction:: pytest_cmdline_main
 
 .. _`initialization-hooks`:
@@ -683,35 +687,50 @@ Initialization hooks
 
 Initialization hooks called for plugins and ``conftest.py`` files.
 
+.. hook:: pytest_addoption
 .. autofunction:: pytest_addoption
+.. hook:: pytest_addhooks
 .. autofunction:: pytest_addhooks
+.. hook:: pytest_configure
 .. autofunction:: pytest_configure
+.. hook:: pytest_unconfigure
 .. autofunction:: pytest_unconfigure
+.. hook:: pytest_sessionstart
 .. autofunction:: pytest_sessionstart
+.. hook:: pytest_sessionfinish
 .. autofunction:: pytest_sessionfinish
 
+.. hook:: pytest_plugin_registered
 .. autofunction:: pytest_plugin_registered
 
 Collection hooks
 ~~~~~~~~~~~~~~~~
 
 ``pytest`` calls the following hooks for collecting files and directories:
 
+.. hook:: pytest_collection
 .. autofunction:: pytest_collection
+.. hook:: pytest_ignore_collect
 .. autofunction:: pytest_ignore_collect
+.. hook:: pytest_collect_file
 .. autofunction:: pytest_collect_file
+.. hook:: pytest_pycollect_makemodule
 .. autofunction:: pytest_pycollect_makemodule
 
 For influencing the collection of objects in Python modules
 you can use the following hook:
 
+.. hook:: pytest_pycollect_makeitem
 .. autofunction:: pytest_pycollect_makeitem
+.. hook:: pytest_generate_tests
 .. autofunction:: pytest_generate_tests
+.. hook:: pytest_make_parametrize_id
 .. autofunction:: pytest_make_parametrize_id
 
 After collection is complete, you can modify the order of
 items, delete or otherwise amend the test items:
 
+.. hook:: pytest_collection_modifyitems
 .. autofunction:: pytest_collection_modifyitems
 
 .. note::
@@ -725,13 +744,21 @@ Test running (runtest) hooks
 
 All runtest related hooks receive a :py:class:`pytest.Item <pytest.Item>` object.
 
+.. hook:: pytest_runtestloop
 .. autofunction:: pytest_runtestloop
+.. hook:: pytest_runtest_protocol
 .. autofunction:: pytest_runtest_protocol
+.. hook:: pytest_runtest_logstart
 .. autofunction:: pytest_runtest_logstart
+.. hook:: pytest_runtest_logfinish
 .. autofunction:: pytest_runtest_logfinish
+.. hook:: pytest_runtest_setup
 .. autofunction:: pytest_runtest_setup
+.. hook:: pytest_runtest_call
 .. autofunction:: pytest_runtest_call
+.. hook:: pytest_runtest_teardown
 .. autofunction:: pytest_runtest_teardown
+.. hook:: pytest_runtest_makereport
 .. autofunction:: pytest_runtest_makereport
 
 For deeper understanding you may look at the default implementation of
@@ -740,33 +767,49 @@ in ``_pytest.pdb`` which interacts with ``_pytest.capture``
 and its input/output capturing in order to immediately drop
 into interactive debugging when a test failure occurs.
 
+.. hook:: pytest_pyfunc_call
 .. autofunction:: pytest_pyfunc_call
 
 Reporting hooks
 ~~~~~~~~~~~~~~~
 
 Session related reporting hooks:
 
+.. hook:: pytest_collectstart
 .. autofunction:: pytest_collectstart
+.. hook:: pytest_make_collect_report
 .. autofunction:: pytest_make_collect_report
+.. hook:: pytest_itemcollected
 .. autofunction:: pytest_itemcollected
+.. hook:: pytest_collectreport
 .. autofunction:: pytest_collectreport
+.. hook:: pytest_deselected
 .. autofunction:: pytest_deselected
+.. hook:: pytest_report_header
 .. autofunction:: pytest_report_header
+.. hook:: pytest_report_collectionfinish
 .. autofunction:: pytest_report_collectionfinish
+.. hook:: pytest_report_teststatus
 .. autofunction:: pytest_report_teststatus
+.. hook:: pytest_terminal_summary
 .. autofunction:: pytest_terminal_summary
+.. hook:: pytest_fixture_setup
 .. autofunction:: pytest_fixture_setup
+.. hook:: pytest_fixture_post_finalizer
 .. autofunction:: pytest_fixture_post_finalizer
+.. hook:: pytest_warning_recorded
 .. autofunction:: pytest_warning_recorded
 
 Central hook for reporting about test execution:
 
+.. hook:: pytest_runtest_logreport
 .. autofunction:: pytest_runtest_logreport
 
 Assertion related hooks:
 
+.. hook:: pytest_assertrepr_compare
 .. autofunction:: pytest_assertrepr_compare
+.. hook:: pytest_assertion_pass
 .. autofunction:: pytest_assertion_pass
 
 
@@ -776,9 +819,13 @@ Debugging/Interaction hooks
 There are few hooks which can be used for special
 reporting or interaction with exceptions:
 
+.. hook:: pytest_internalerror
 .. autofunction:: pytest_internalerror
+.. hook:: pytest_keyboard_interrupt
 .. autofunction:: pytest_keyboard_interrupt
+.. hook:: pytest_exception_interact
 .. autofunction:: pytest_exception_interact
+.. hook:: pytest_enter_pdb
 .. autofunction:: pytest_enter_pdb
 
 

src/_pytest/hookspec.py

@@ -162,7 +162,7 @@ def pytest_cmdline_preparse(config: "Config", args: List[str]) -> None:
     """(**Deprecated**) modify command line arguments before option parsing.
 
     This hook is considered deprecated and will be removed in a future pytest version. Consider
-    using :func:`pytest_load_initial_conftests` instead.
+    using :hook:`pytest_load_initial_conftests` instead.
 
     .. note::
         This hook will not be called for ``conftest.py`` files, only for setuptools plugins.
@@ -466,7 +466,7 @@ def pytest_runtest_logstart(
 ) -> None:
     """Called at the start of running the runtest protocol for a single item.
 
-    See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
 
     :param str nodeid: Full node ID of the item.
     :param location: A tuple of ``(filename, lineno, testname)``.
@@ -478,7 +478,7 @@ def pytest_runtest_logfinish(
 ) -> None:
     """Called at the end of running the runtest protocol for a single item.
 
-    See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
 
     :param str nodeid: Full node ID of the item.
     :param location: A tuple of ``(filename, lineno, testname)``.
@@ -525,7 +525,7 @@ def pytest_runtest_makereport(
     """Called to create a :class:`~pytest.TestReport` for each of
     the setup, call and teardown runtest phases of a test item.
 
-    See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
 
     :param call: The :class:`~pytest.CallInfo` for the phase.
 
@@ -537,7 +537,7 @@ def pytest_runtest_logreport(report: "TestReport") -> None:
     """Process the :class:`~pytest.TestReport` produced for each
     of the setup, call and teardown runtest phases of an item.
 
-    See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
     """
 
 
@@ -556,7 +556,7 @@ def pytest_report_from_serializable(
     data: Dict[str, Any],
 ) -> Optional[Union["CollectReport", "TestReport"]]:
     """Restore a report object previously serialized with
-    :func:`pytest_report_to_serializable`."""
+    :hook:`pytest_report_to_serializable`."""
 
 
 # -------------------------------------------------------------------------
@@ -859,10 +859,10 @@ def pytest_exception_interact(
     """Called when an exception was raised which can potentially be
     interactively handled.
 
-    May be called during collection (see :py:func:`pytest_make_collect_report`),
+    May be called during collection (see :hook:`pytest_make_collect_report`),
     in which case ``report`` is a :class:`CollectReport`.
 
-    May be called during runtest of an item (see :py:func:`pytest_runtest_protocol`),
+    May be called during runtest of an item (see :hook:`pytest_runtest_protocol`),
     in which case ``report`` is a :class:`TestReport`.
 
     This hook is not called if the exception that was raised is an internal

src/_pytest/main.py

@@ -605,8 +605,7 @@ def perform_collect(
     ) -> Sequence[Union[nodes.Item, nodes.Collector]]:
         """Perform the collection phase for this session.
 
-        This is called by the default
-        :func:`pytest_collection <_pytest.hookspec.pytest_collection>` hook
+        This is called by the default :hook:`pytest_collection` hook
         implementation; see the documentation of this hook for more details.
         For testing purposes, it may also be called directly on a fresh
         ``Session``.

src/_pytest/python.py

@@ -985,7 +985,7 @@ def id(self) -> str:
 
 @final
 class Metafunc:
-    """Objects passed to the :func:`pytest_generate_tests <_pytest.hookspec.pytest_generate_tests>` hook.
+    """Objects passed to the :hook:`pytest_generate_tests` hook.
 
     They help to inspect a test function and to generate tests according to
     test configuration or values specified in the class or module where a