Add docs for internal warnings and introduce PytestDeprecationWarning

Fix #2477

src/_pytest/warning_types.py

@@ -1,6 +1,22 @@
 class PytestWarning(UserWarning):
-    """Base class for all warnings emitted by pytest"""
+    """
+    Bases: :class:`UserWarning`.
+
+    Base class for all warnings emitted by pytest.
+    """
 
 
-class RemovedInPytest4Warning(PytestWarning, DeprecationWarning):
-    """warning class for features that will be removed in pytest 4.0"""
+class PytestDeprecationWarning(PytestWarning, DeprecationWarning):
+    """
+    Bases: :class:`pytest.PytestWarning`, :class:`DeprecationWarning`.
+
+    Warning class for features that will be removed in a future version.
+    """
+
+
+class RemovedInPytest4Warning(PytestDeprecationWarning):
+    """
+    Bases: :class:`pytest.PytestDeprecationWarning`.
+
+    Warning class for features scheduled to be removed in pytest 4.0.
+    """

src/pytest.py

@@ -20,7 +20,11 @@ from _pytest.nodes import Item, Collector, File
 from _pytest.fixtures import fillfixtures as _fillfuncargs
 from _pytest.python import Package, Module, Class, Instance, Function, Generator
 from _pytest.python_api import approx, raises
-from _pytest.warning_types import PytestWarning, RemovedInPytest4Warning
+from _pytest.warning_types import (
+    PytestWarning,
+    PytestDeprecationWarning,
+    RemovedInPytest4Warning,
+)
 
 set_trace = __pytestPDB.set_trace
 
@@ -50,6 +54,7 @@ __all__ = [
     "Package",
     "param",
     "PytestWarning",
+    "PytestDeprecationWarning",
     "raises",
     "register_assert_rewrite",
     "RemovedInPytest4Warning",