From 9088f50c989aa97d32ab510741d3447340e73c6d Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Wed, 22 Jul 2020 09:00:46 +0200 Subject: [PATCH] Doc: Mention Sphinx directive for docstrings For contributing to semver, every substantial change should also introduce a Sphinx directive (versionadded, versionchanged, or deprecated) to help our readers. --- docs/development.rst | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index dad14641..3f5e9b6d 100644 --- 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