6.3. 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 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 API Reference 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.