From ec7567ce4101f5359a795744041376d6ae3ef15f Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Sun, 15 Mar 2020 19:15:56 +0100 Subject: Improve documentation about Sphinx's deprecation warnings --- CONTRIBUTING.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'CONTRIBUTING.rst') 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 `) +for more details. + Unit Testing ------------ -- cgit v1.2.3