Improve docs of pytest.importorskip (#5718)

Improve docs of pytest.importorskip

doc/en/reference.rst

@@ -27,6 +27,8 @@ pytest.skip
 
 .. autofunction:: _pytest.outcomes.skip(msg, [allow_module_level=False])
 
+.. _`pytest.importorskip ref`:
+
 pytest.importorskip
 ~~~~~~~~~~~~~~~~~~~
 

doc/en/skipping.rst

@@ -179,16 +179,15 @@ information.
 Skipping on a missing import dependency
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use the following helper at module level
-or within a test or test setup function:
+You can skip tests on a missing import by using :ref:`pytest.importorskip ref`
+at module level or within a test or test setup function.
 
 .. code-block:: python
 
     docutils = pytest.importorskip("docutils")
 
-If ``docutils`` cannot be imported here, this will lead to a
-skip outcome of the test.  You can also skip based on the
-version number of a library:
+If ``docutils`` cannot be imported here, this will lead to a skip outcome of
+the test. You can also skip based on the version number of a library:
 
 .. code-block:: python
 

src/_pytest/outcomes.py

@@ -143,14 +143,21 @@ xfail.Exception = XFailed  # type: ignore
 
 
 def importorskip(modname, minversion=None, reason=None):
-    """Imports and returns the requested module ``modname``, or skip the current test
-    if the module cannot be imported.
+    """Imports and returns the requested module ``modname``, or skip the
+    current test if the module cannot be imported.
 
     :param str modname: the name of the module to import
-    :param str minversion: if given, the imported module ``__version__`` attribute must be
-        at least this minimal version, otherwise the test is still skipped.
-    :param str reason: if given, this reason is shown as the message when the module
-        cannot be imported.
+    :param str minversion: if given, the imported module ``__version__``
+        attribute must be at least this minimal version, otherwise the test is
+        still skipped.
+    :param str reason: if given, this reason is shown as the message when the
+        module cannot be imported.
+    :returns: The imported module. This should be assigned to its canonical
+        name.
+
+    Example::
+
+        docutils = pytest.importorskip("docutils")
     """
     import warnings