Fix #310: Correct API documentation

tomschr · tomschr · commit dcdcd2ab7447 · 2020-11-03T21:23:23.000+01:00
* Remove all automatic generation and use a more
  "semi-manual" approach (gives more control)
* Improve docstrings in semver module
* Remove docstrings in some dunder methods; Sphinx
  and autodoc uses the docstring from the parent class
* Remove sphinx-apidoc command from :file:`tox.ini`
diff --git a/changelog.d/310.bugfix.rst b/changelog.d/310.bugfix.rst
@@ -0,0 +1,3 @@
+Rework API documentation.
+Follow a more "semi-manual" attempt and add auto directives
+into :file:`docs/api.rst`.
diff --git a/docs/_api/semver.__about__.rst b/docs/_api/semver.__about__.rst
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -35,6 +35,10 @@ div.related.top nav {
     font-weight: 700;
 }
 
+.py.class {
+    margin-top: 1.5em;
+}
+
 .py.method {
     padding-top: 0.25em;
     padding-bottom: 1.25em;
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,10 +1,63 @@
 .. _api:
 
-###
-API
-###
+API Reference
+=============
 
-.. toctree::
-   :maxdepth: 4
+.. currentmodule:: semver
 
-   _api/semver
+
+Metadata :mod:`semver.__about__`
+--------------------------------
+
+.. automodule:: semver.__about__
+
+
+Deprecated Functions in :mod:`semver._deprecated`
+-------------------------------------------------
+
+.. automodule:: semver._deprecated
+
+.. autofunction:: semver._deprecated.deprecated
+
+
+CLI Parsing :mod:`semver.cli`
+-----------------------------
+
+.. automodule:: semver.cli
+
+.. autofunction:: semver.cli.cmd_bump
+
+.. autofunction:: semver.cli.cmd_check
+
+.. autofunction:: semver.cli.cmd_compare
+
+.. autofunction:: semver.cli.createparser
+
+.. autofunction:: semver.cli.main
+
+.. autofunction:: semver.cli.process
+
+
+Entry point :mod:`semver.__main__`
+----------------------------------
+
+.. automodule:: semver.__main__
+
+
+
+Version Handling :mod:`semver.version`
+--------------------------------------
+
+.. automodule:: semver.version
+
+.. autofunction:: semver.version.cmp
+
+.. autofunction:: semver.version.ensure_str
+
+.. autofunction:: semver.version.comparator
+
+.. autoclass:: semver.version.VersionInfo
+
+.. autoclass:: semver.version.Version
+   :members:
+   :special-members: __iter__, __eq__, __ne__, __lt__, __le__, __gt__, __ge__, __getitem__, __hash__, __repr__, __str__
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,7 +21,8 @@
 import re
 import sys
 
-sys.path.insert(0, os.path.abspath("../src/"))
+SRC_DIR = os.path.abspath("../src/")
+sys.path.insert(0, SRC_DIR)
 # from semver import __version__  # noqa: E402
 
 
@@ -58,15 +59,16 @@ def find_version(*file_paths):
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
 ]
 
+# Autodoc configuration
 autoclass_content = "class"
-autodoc_default_options = {}
-
+autodoc_typehints = "signature"
+autodoc_member_order = "alphabetical"
+add_function_parentheses = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
diff --git a/src/semver/__about__.py b/src/semver/__about__.py
@@ -4,7 +4,15 @@
 Contains information about semver's version, the implemented version
 of the semver specifictation, author, maintainers, and description.
 
+.. autodata:: __author__
+
+.. autodata:: __description__
+
+.. autodata:: __maintainer__
+
 .. autodata:: __version__
+
+.. autodata:: SEMVER_SPEC_VERSION
 """
 
 #: Semver version
diff --git a/src/semver/_types.py b/src/semver/_types.py
@@ -1,3 +1,5 @@
+"""Typing for semver."""
+
 from typing import Union, Optional, Tuple, Dict, Iterable, Callable, TypeVar
 
 VersionPart = Union[int, Optional[str]]
diff --git a/src/semver/cli.py b/src/semver/cli.py
@@ -1,4 +1,14 @@
-"""CLI parsing for :command:`pysemver` command."""
+"""
+CLI parsing for :command:`pysemver` command.
+
+Each command in :command:`pysemver` is mapped to a ``cmd_`` function.
+The :func:`main <semver.cli.main>` function calls
+:func:`createparser <semver.cli.createparser>` and
+:func:`process <semver.cli.process>` to parse and process
+all the commandline options.
+
+The result of each command is printed on stdout.
+"""
 
 import argparse
 import sys
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -43,18 +43,14 @@ def ensure_str(s: String, encoding="utf-8", errors="strict") -> str:
     * `bytes` -> decoded to `str`
 
     :param s: the string to convert
-    :type s: str | bytes
     :param encoding: the encoding to apply, defaults to "utf-8"
-    :type encoding: str
     :param errors: set a different error handling scheme,
        defaults to "strict".
        Other possible values are `ignore`, `replace`, and
        `xmlcharrefreplace` as well as any other name
        registered with :func:`codecs.register_error`.
-    :type errors: str
     :raises TypeError: if ``s`` is not str or bytes type
     :return: the converted string
-    :rtype: str
     """
     if isinstance(s, bytes):
         s = s.decode(encoding, errors)
@@ -218,7 +214,7 @@ def build(self, value):
 
     def to_tuple(self) -> VersionTuple:
         """
-        Convert the VersionInfo object to a tuple.
+        Convert the Version object to a tuple.
 
         .. versionadded:: 2.10.0
            Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
@@ -233,7 +229,7 @@ def to_tuple(self) -> VersionTuple:
 
     def to_dict(self) -> VersionDict:
         """
-        Convert the VersionInfo object to an OrderedDict.
+        Convert the Version object to an OrderedDict.
 
         .. versionadded:: 2.10.0
            Renamed ``VersionInfo._asdict`` to ``VersionInfo.to_dict`` to
@@ -257,7 +253,7 @@ def to_dict(self) -> VersionDict:
         )
 
     def __iter__(self) -> VersionIterator:
-        """Implement iter(self)."""
+        """Return iter(self)."""
         yield from self.to_tuple()
 
     @staticmethod
@@ -300,7 +296,6 @@ def bump_minor(self) -> "Version":
 
         :return: new object with the raised minor part
 
-
         >>> ver = semver.parse("3.4.5")
         >>> ver.bump_minor()
         Version(major=3, minor=5, patch=0, prerelease=None, build=None)
@@ -313,8 +308,7 @@ def bump_patch(self) -> "Version":
         Raise the patch part of the version, return a new object but leave self
         untouched.
 
-                :return: new object with the raised patch part
-
+        :return: new object with the raised patch part
 
         >>> ver = semver.parse("3.4.5")
         >>> ver.bump_patch()
@@ -328,7 +322,7 @@ def bump_prerelease(self, token: str = "rc") -> "Version":
         Raise the prerelease part of the version, return a new object but leave
         self untouched.
 
-        :param token: defaults to 'rc'
+        :param token: defaults to ``rc``
         :return: new object with the raised prerelease part
 
         >>> ver = semver.parse("3.4.5")
@@ -345,7 +339,7 @@ def bump_build(self, token: str = "build") -> "Version":
         Raise the build part of the version, return a new object but leave self
         untouched.
 
-        :param token: defaults to 'build'
+        :param token: defaults to ``build``
         :return: new object with the raised build part
 
         >>> ver = semver.parse("3.4.5-rc.1+build.9")
@@ -365,7 +359,6 @@ def compare(self, other: Comparable) -> int:
         :return: The return value is negative if ver1 < ver2,
              zero if ver1 == ver2 and strictly positive if ver1 > ver2
 
-
         >>> semver.compare("2.0.0")
         -1
         >>> semver.compare("1.0.0")
@@ -481,14 +474,17 @@ def __getitem__(
         self, index: Union[int, slice]
     ) -> Union[int, Optional[str], Tuple[Union[int, str], ...]]:
         """
-        self.__getitem__(index) <==> self[index] Implement getitem. If the part
-        requested is undefined, or a part of the range requested is undefined,
-        it will throw an index error. Negative indices are not supported.
+        self.__getitem__(index) <==> self[index] Implement getitem.
+
+        If the part  requested is undefined, or a part of the range requested
+        is undefined, it will throw an index error.
+        Negative indices are not supported.
 
         :param Union[int, slice] index: a positive integer indicating the
                offset or a :func:`slice` object
         :raises IndexError: if index is beyond the range or a part is None
         :return: the requested part of the version at position index
+
         >>> ver = semver.Version.parse("3.4.5")
         >>> ver[0], ver[1], ver[2]
         (3, 4, 5)
@@ -519,7 +515,6 @@ def __repr__(self) -> str:
         return "%s(%s)" % (type(self).__name__, s)
 
     def __str__(self) -> str:
-        """str(self)"""
         version = "%d.%d.%d" % (self.major, self.minor, self.patch)
         if self.prerelease:
             version += "-%s" % self.prerelease
@@ -533,7 +528,9 @@ def __hash__(self) -> int:
     def finalize_version(self) -> "Version":
         """
         Remove any prerelease and build metadata from the version.
+
         :return: a new instance with the finalized version string
+
         >>> str(semver.Version.parse('1.2.3-rc.5').finalize_version())
         '1.2.3'
         """
@@ -545,12 +542,12 @@ def match(self, match_expr: str) -> bool:
         Compare self to match a match expression.
 
         :param match_expr: operator and version; valid operators are
-              <   smaller than
-              >   greater than
-              >=  greator or equal than
-              <=  smaller or equal than
-              ==  equal
-              !=  not equal
+              ``<```   smaller than
+              ``>``   greater than
+              ``>=``  greator or equal than
+              ``<=``  smaller or equal than
+              ``==``  equal
+              ``!=``  not equal
         :return: True if the expression matches the version, otherwise False
 
         >>> semver.Version.parse("2.0.0").match(">=1.0.0")
@@ -589,18 +586,18 @@ def match(self, match_expr: str) -> bool:
     @classmethod
     def parse(cls, version: String) -> "Version":
         """
-        Parse version string to a VersionInfo instance.
+        Parse version string to a Version instance.
 
         .. versionchanged:: 2.11.0
            Changed method from static to classmethod to
            allow subclasses.
 
         :param version: version string
-        :return: a :class:`VersionInfo` instance
+        :return: a new :class:`Version` instance
         :raises ValueError: if version is invalid
 
         >>> semver.Version.parse('3.4.5-pre.2+build.4')
-        VersionInfo(major=3, minor=4, patch=5, \
+        Version(major=3, minor=4, patch=5, \
 prerelease='pre.2', build='build.4')
         """
         version_str = ensure_str(version)
@@ -624,15 +621,15 @@ def replace(self, **parts: Union[int, Optional[str]]) -> "Version":
           ``major``, ``minor``, ``patch``, ``prerelease``, or ``build``
         :return: the new :class:`Version` object with the changed
           parts
-        :raises TypeError: if ``parts`` contains invalid keys
+        :raises TypeError: if ``parts`` contain invalid keys
         """
         version = self.to_dict()
         version.update(parts)
         try:
             return Version(**version)  # type: ignore
         except TypeError:
             unknownkeys = set(parts) - set(self.to_dict())
-            error = "replace() got %d unexpected keyword " "argument(s): %s" % (
+            error = "replace() got %d unexpected keyword argument(s): %s" % (
                 len(unknownkeys),
                 ", ".join(unknownkeys),
             )
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -12,7 +12,7 @@
 
 @pytest.fixture(autouse=True)
 def add_semver(doctest_namespace):
-    doctest_namespace["Version"] = semver.Version
+    doctest_namespace["Version"] = semver.version.Version
     doctest_namespace["semver"] = semver
     doctest_namespace["coerce"] = coerce
     doctest_namespace["SemVerWithVPrefix"] = SemVerWithVPrefix
diff --git a/tox.ini b/tox.ini
@@ -67,15 +67,7 @@ deps = -r{toxinidir}/docs/requirements.txt
 skip_install = true
 allowlist_externals =
     make
-    rm
     echo
-    sed
-commands_pre =
-    sphinx-apidoc --module-first -f  --separate -H semver -o docs/_api src/semver src/semver/_types.py src/semver/_deprecated.py
-    # we don't need this, it just add another level and it's all in docs/api.rst
-    - rm docs/_api/modules.rst
-    # Include the semver.__about__ module before semver.cli:
-    sed -i '/semver\.cli/i\ \ \ semver.__about__' docs/_api/semver.rst
 commands =
     make -C docs html
 commands_post =

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Rework API documentation.`
	`2`	`+Follow a more "semi-manual" attempt and add auto directives`
	`3`	+into :file:`docs/api.rst`.
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Typing for semver."""`
	`2`	`+`
`1`	`3`	`from typing import Union, Optional, Tuple, Dict, Iterable, Callable, TypeVar`
`2`	`4`
`3`	`5`	`VersionPart = Union[int, Optional[str]]`