Move warnings listing to reference docs

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`:

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>`.

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"