From b095e0de47a684bf7a7a3a7ec49c5457fabf6903 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 9 Aug 2019 21:35:03 +0200
Subject: [PATCH] Improve docs of pytest.importorskip

---
 doc/en/reference.rst    |  2 ++
 doc/en/skipping.rst     |  9 ++++-----
 src/_pytest/outcomes.py | 19 +++++++++++++------
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 7e47ffce0..991050c23 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -27,6 +27,8 @@ pytest.skip
 
 .. autofunction:: _pytest.outcomes.skip(msg, [allow_module_level=False])
 
+.. _`pytest.importorskip ref`:
+
 pytest.importorskip
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst
index eb00a6dfb..57f565472 100644
--- a/doc/en/skipping.rst
+++ b/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
 
diff --git a/src/_pytest/outcomes.py b/src/_pytest/outcomes.py
index 55c30803f..a3b6d4054 100644
--- a/src/_pytest/outcomes.py
+++ b/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