Improve documentation about Sphinx's deprecation warnings

1 files changed, 16 insertions, 3 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 6fd56fb9d..af12e4a5b 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -387,18 +387,31 @@ Sphinx 2.x:
 
 * Sphinx 2.x will contain a backwards-compatible replica of the function
   which will raise a ``RemovedInSphinx40Warning``.
+  This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
+  will not get displayed by default.
 
-* Sphinx 3.x will still contain the backwards-compatible replica.
+* Sphinx 3.x will still contain the backwards-compatible replica, but
+  ``RemovedInSphinx40Warning`` will be a subclass of
+  :exc:`python:DeprecationWarning` then, and gets displayed by default.
 
 * Sphinx 4.0 will remove the feature outright.
 
-The warnings are displayed by default. You can turn off display of these
-warnings with:
+Deprecation warnings
+~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default,
+if :envvar:`python:PYTHONWARNINGS` is not set.
+Therefore you can disable them using:
 
 * ``PYTHONWARNINGS= make html`` (Linux/Mac)
 * ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
 * ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
 
+But you can also explicitly enable the pending ones using e.g.
+``PYTHONWARNINGS=default`` (see the
+:ref:`Python docs on configuring warnings <python:describing-warning-filters>`)
+for more details.
+
 Unit Testing
 ------------