Document who to turn on deprecation warnings

tomschr · tomschr · commit d4348fa17e1a · 2020-04-11T14:26:02.000+02:00
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -42,7 +42,8 @@ creating a version:
 
     Module level functions are marked as *deprecated* in version 2.9.2 now.
     These functions will be removed in semver 3.
-    For details, see section :ref:`sec_replace_deprecated_functions`.
+    For details, see the sections :ref:`sec_replace_deprecated_functions` and
+    :ref:`sec_display_deprecation_warnings`.
 
 
 A version can be created in different ways:
@@ -475,3 +476,39 @@ them with code which is compatible for future versions:
      >>> s2 = str(semver.VersionInfo.parse('1.2.3').replace(major=2, patch=10))
      >>> s1 == s2
      True
+
+
+.. _sec_display_deprecation_warnings:
+
+Displaying Deprecation Warnings
+-------------------------------
+
+By default,  deprecation warnings are `ignored in Python <https://docs.python.org/3/library/warnings.html#warning-categories>`_.
+This also affects semver's own warnings.
+
+It is recommended that you turn on deprecation warnings in your scripts. Use one of
+the following methods:
+
+* Use the option `-Wd <https://docs.python.org/3/using/cmdline.html#cmdoption-w>`_
+  to enable default warnings:
+
+  * Directly running the Python command::
+
+       $ python3 -Wd scriptname.py
+
+  * Add the option in the shebang line (something like ``#!/usr/bin/python3``)
+    after the command::
+
+       #!/usr/bin/python3 -Wd
+
+* In your own scripts add a filter to ensure that *all* warnings are displayed:
+
+   .. code-block:: python
+
+       import warnings
+       warnings.simplefilter("default")
+       # Call your semver code
+
+   For further details, see the section
+   `Overriding the default filter <https://docs.python.org/3/library/warnings.html#overriding-the-default-filter>`_
+   of the Python documentation.
