From 77adb33ec613bb64e0a68d4bc9c9393c2dab08f5 Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Thu, 5 Mar 2020 02:56:18 +0100
Subject: [PATCH] doc: use show-inheritance with warnings, revisit docstrings

Revisits the docstring for `PytestExperimentalApiWarning` and
`PytestUnhandledCoroutineWarning`.
---
 doc/en/warnings.rst          |  9 ++++++
 src/_pytest/warning_types.py | 56 +++++++++---------------------------
 2 files changed, 23 insertions(+), 42 deletions(-)

diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index 013564c2d..550e294ef 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -416,19 +416,28 @@ features.
 The following warning types are used by pytest and are part of the public API:
 
 .. autoclass:: pytest.PytestWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestAssertRewriteWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestCacheWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestCollectionWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestConfigWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestDeprecationWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestExperimentalApiWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestUnhandledCoroutineWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestUnknownMarkWarning
+   :show-inheritance:
diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py
index 2e03c578c..87ab72c2d 100644
--- a/src/_pytest/warning_types.py
+++ b/src/_pytest/warning_types.py
@@ -11,71 +11,46 @@ if TYPE_CHECKING:
 
 
 class PytestWarning(UserWarning):
-    """
-    Bases: :class:`UserWarning`.
-
-    Base class for all warnings emitted by pytest.
-    """
+    """Base class for all warnings emitted by pytest."""
 
     __module__ = "pytest"
 
 
 class PytestAssertRewriteWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted by the pytest assert rewrite module.
-    """
+    """Warning emitted by the pytest assert rewrite module."""
 
     __module__ = "pytest"
 
 
 class PytestCacheWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted by the cache plugin in various situations.
-    """
+    """Warning emitted by the cache plugin in various situations."""
 
     __module__ = "pytest"
 
 
 class PytestConfigWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted for configuration issues.
-    """
+    """Warning emitted for configuration issues."""
 
     __module__ = "pytest"
 
 
 class PytestCollectionWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted when pytest is not able to collect a file or symbol in a module.
-    """
+    """Warning emitted when pytest is not able to collect a file or symbol in a module."""
 
     __module__ = "pytest"
 
 
 class PytestDeprecationWarning(PytestWarning, DeprecationWarning):
-    """
-    Bases: :class:`pytest.PytestWarning`, :class:`DeprecationWarning`.
-
-    Warning class for features that will be removed in a future version.
-    """
+    """Warning class for features that will be removed in a future version."""
 
     __module__ = "pytest"
 
 
 class PytestExperimentalApiWarning(PytestWarning, FutureWarning):
-    """
-    Bases: :class:`pytest.PytestWarning`, :class:`FutureWarning`.
+    """Warning category used to denote experiments in pytest.
 
-    Warning category used to denote experiments in pytest. Use sparingly as the API might change or even be
-    removed completely in future version
+    Use sparingly as the API might change or even be removed completely in a
+    future version.
     """
 
     __module__ = "pytest"
@@ -90,22 +65,19 @@ class PytestExperimentalApiWarning(PytestWarning, FutureWarning):
 
 
 class PytestUnhandledCoroutineWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
+    """Warning emitted for an unhandled coroutine.
 
-    Warning emitted when pytest encounters a test function which is a coroutine,
-    but it was not handled by any async-aware plugin. Coroutine test functions
-    are not natively supported.
+    A coroutine was encountered when collecting test functions, but was not
+    handled by any async-aware plugin.
+    Coroutine test functions are not natively supported.
     """
 
     __module__ = "pytest"
 
 
 class PytestUnknownMarkWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
+    """Warning emitted on use of unknown markers.
 
-    Warning emitted on use of unknown markers.
     See https://docs.pytest.org/en/latest/mark.html for details.
     """