From 90d543394262abe31ee38840d60b5027dc99ae51 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Sat, 11 Jul 2020 11:58:56 -0300
Subject: [PATCH] Move warnings listing to reference docs

---
 doc/en/reference.rst         | 41 +++++++++++++++++++++++++++++++++---
 doc/en/warnings.rst          | 31 +--------------------------
 src/_pytest/warning_types.py |  2 +-
 3 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index d81ba9bc7ea..b753514f046 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -1021,10 +1021,45 @@ When set (regardless of value), pytest will use color in terminal output.
 Exceptions
 ----------
 
-UsageError
-~~~~~~~~~~
-
 .. autoclass:: _pytest.config.UsageError()
+    :show-inheritance:
+
+.. _`warnings ref`:
+
+Warnings
+--------
+
+Custom warnings generated in some situations such as improper usage or deprecated features.
+
+.. 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:
+
+
+Consult the :ref:`internal-warnings` section in the documentation for more information.
 
 
 .. _`ini options ref`:
diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index 30ea529650c..d1e27ecad21 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -381,8 +381,6 @@ custom error message.
 Internal pytest warnings
 ------------------------
 
-
-
 pytest may generate its own warnings in some situations, such as improper usage or deprecated features.
 
 For example, pytest will emit a warning if it encounters a class that matches :confval:`python_classes` but also
@@ -415,31 +413,4 @@ These warnings might be filtered using the same builtin mechanisms used to filte
 Please read our :ref:`backwards-compatibility` to learn how we proceed about deprecating and eventually removing
 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:
+The full list of warnings is listed in :ref:`the reference documentation <warnings ref>`.
diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py
index 494b92efff6..6f3b88da8b8 100644
--- a/src/_pytest/warning_types.py
+++ b/src/_pytest/warning_types.py
@@ -78,7 +78,7 @@ class PytestUnhandledCoroutineWarning(PytestWarning):
 class PytestUnknownMarkWarning(PytestWarning):
     """Warning emitted on use of unknown markers.
 
-    See https://docs.pytest.org/en/stable/mark.html for details.
+    See :ref:`mark` for details.
     """
 
     __module__ = "pytest"