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

@@ -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
 ------------------------

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
 ~~~~~~~~~~~~~~~~~~~