From a5ee9f2ecd22576ef6e91a00c957ec190ce87dc6 Mon Sep 17 00:00:00 2001
From: Ran Benita <ran@unusedvar.com>
Date: Wed, 6 Dec 2023 23:58:07 +0200
Subject: [PATCH] doc: document `pytest.{hookspec,hookimpl}` in the API
Reference
Makes sense for them to be there; also allows for Sphinx refs.
---
doc/en/how-to/writing_hook_functions.rst | 5 +----
doc/en/reference/reference.rst | 24 ++++++++++++++++++++++--
2 files changed, 23 insertions(+), 6 deletions(-)
diff --git a/doc/en/how-to/writing_hook_functions.rst b/doc/en/how-to/writing_hook_functions.rst
index 527aeec81..ec290349c 100644
--- a/doc/en/how-to/writing_hook_functions.rst
+++ b/doc/en/how-to/writing_hook_functions.rst
@@ -59,10 +59,6 @@ The remaining hook functions will not be called in this case.
hook wrappers: executing around other hooks
-------------------------------------------------
-.. currentmodule:: _pytest.core
-
-
-
pytest plugins can implement hook wrappers which wrap the execution
of other hook implementations. A hook wrapper is a generator function
which yields exactly once. When pytest invokes hooks it first executes
@@ -165,6 +161,7 @@ Here is the order of execution:
It's possible to use ``tryfirst`` and ``trylast`` also on hook wrappers
in which case it will influence the ordering of hook wrappers among each other.
+.. _`declaringhooks`:
Declaring new hooks
------------------------
diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst
index 254973709..2dcad7d58 100644
--- a/doc/en/reference/reference.rst
+++ b/doc/en/reference/reference.rst
@@ -612,10 +612,30 @@ Hooks
**Tutorial**: :ref:`writing-plugins`
-.. currentmodule:: _pytest.hookspec
-
Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
+@pytest.hookimpl
+~~~~~~~~~~~~~~~~
+
+.. function:: pytest.hookimpl
+ :decorator:
+
+ pytest's decorator for marking functions as hook implementations.
+
+ See :ref:`writinghooks` and :func:`pluggy.HookimplMarker`.
+
+@pytest.hookspec
+~~~~~~~~~~~~~~~~
+
+.. function:: pytest.hookspec
+ :decorator:
+
+ pytest's decorator for marking functions as hook specifications.
+
+ See :ref:`declaringhooks` and :func:`pluggy.HookspecMarker`.
+
+.. currentmodule:: _pytest.hookspec
+
Bootstrapping hooks
~~~~~~~~~~~~~~~~~~~