Add docs for internal warnings and introduce PytestDeprecationWarning

Fix #2477

doc/en/warnings.rst

@@ -296,3 +296,52 @@ You can also use it as a contextmanager::
     def test_global():
         with pytest.deprecated_call():
             myobject.deprecated_method()
+
+
+Internal pytest warnings
+------------------------
+
+.. versionadded:: 3.8
+
+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
+defines an ``__init__`` constructor, as this prevents the class from being instantiated:
+
+.. code-block:: python
+
+    # content of test_pytest_warnings.py
+    class Test:
+        def __init__(self):
+            pass
+
+        def test_foo(self):
+            assert 1 == 1
+
+::
+
+    $ pytest test_pytest_warnings.py -q
+    ======================================== warnings summary =========================================
+    test_pytest_warnings.py:1
+      $REGENDOC_TMPDIR/test_pytest_warnings.py:1: PytestWarning: cannot collect test class 'Test' because it has a __init__ constructor
+        class Test:
+
+    -- Docs: http://doc.pytest.org/en/latest/warnings.html
+    1 warnings in 0.01 seconds
+
+
+
+These warnings might be filtered using the same builtin mechanisms used to filter other types of warnings.
+
+Following our :ref:`backwards-compatibility`, deprecated features will be kept *at least* two minor releases. After that,
+they will changed so they by default raise errors instead of just warnings, so users can adapt to it on their own time
+if not having done so until now. In a later release the deprecated feature will be removed completely.
+
+The following warning types ares used by pytest and are part of the public API:
+
+.. autoclass:: pytest.PytestWarning
+
+.. autoclass:: pytest.PytestDeprecationWarning
+
+.. autoclass:: pytest.RemovedInPytest4Warning
+

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):
+class PytestDeprecationWarning(PytestWarning, DeprecationWarning):
-    """warning class for features that will be removed in pytest 4.0"""
+    """
+    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",