Doc: Mention Sphinx directive for docstrings

tomschr · tomschr · commit 9088f50c989a · 2020-07-22T09:00:46.000+02:00
For contributing to semver, every substantial change
should also introduce a Sphinx directive (versionadded,
versionchanged, or deprecated) to help our readers.
diff --git a/docs/development.rst b/docs/development.rst
@@ -154,8 +154,9 @@ documentation includes:
 
   * **A docstring**
 
-    Each docstring contains a summary line, a linebreak, the description
-    of its arguments in `Sphinx style`_, and an optional doctest.
+    Each docstring contains a summary line, a linebreak, an optional
+    directive (see next item), the description of its arguments in
+    `Sphinx style`_, and an optional doctest.
     The docstring is extracted and reused in the :ref:`api` section.
     An appropriate docstring should look like this::
 
@@ -177,6 +178,43 @@ documentation includes:
 
             """
 
+  * **An optional directive**
+
+    If you introduce a new feature, change a function/method, or remove something,
+    it is a good practice to introduce Sphinx directives into the docstring.
+    This gives the reader an idea what version is affected by this change.
+
+    The first required argument, ``VERSION``, defines the version when this change
+    was introduced. You can choose from:
+
+    * ``.. versionadded:: VERSION``
+
+      Use this directive to describe a new feature.
+
+    * ``.. versionchanged:: VERSION``
+
+      Use this directive to describe when something has changed, for example,
+      new parameters were added, changed side effects, different return values, etc.
+
+    * ``.. deprecated:: VERSION``
+
+      Use this directive when a feature is deprecated. Describe what should
+      be used instead, if appropriate.
+
+
+    Add such a directive *after* the summary line, if needed.
+    An appropriate directive could look like this::
+
+        def to_tuple(self):
+            """
+            Convert the VersionInfo object to a tuple.
+
+            .. versionadded:: 2.10.0
+               Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
+               make this function available in the public API.
+            [...]
+            """
+
   * **The documentation**
 
     A docstring is good, but in most cases it's too dense. Describe how
