1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
.. _doc:
Documenting semver
==================
Documenting the features of semver is very important. It gives our developers
an overview what is possible with semver, how it "feels", and how it is
used efficiently.
.. note::
To build the documentation locally use the following command::
$ tox -e docs
The built documentation is available in :file:`docs/_build/html`.
A new feature is *not* complete if it isn't proberly documented. A good
documentation includes:
* **Type annotations**
This library supports type annotations. Therefore, each function
or method requires types for each arguments and return objects.
Exception of this rule is ``self``.
* **A docstring**
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 looks like this::
def to_tuple(self) -> VersionTuple:
"""
Convert the Version object to a tuple.
.. versionadded:: 2.10.0
Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
make this function available in the public API.
:return: a tuple with all the parts
>>> semver.Version(5, 3, 1).to_tuple()
(5, 3, 1, None, None)
"""
* **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, as shown above.
* **The documentation**
A docstring is good, but in most cases it is too short. API documentation
cannot replace good user documentation.
Describe *how* to use your new feature in the documentation.
Here you can give your readers more examples, describe it in a broader
context, or show edge cases.
.. _Sphinx style: https://sphinx-rtd-tutorial.rtfd.io/en/latest/docstrings.html
|
