Fix #312: Rework Usage section

tomschr · tomschr · commit a8dd4eae7a57 · 2020-11-04T12:09:52.000+01:00
* Correct :class: directive and use :class:`~semver.version.Version`
* Mention the rename of VersionInfo -&gt; Version class
* Remove semver. prefix in doctests to make examples shorter
* Correct some references to dunder methods like __getitem__, __gt__ etc.
* Use :py:exec: reference to Python exceptions.
* Remove inconsistencies and mention module level function as
  deprecated and discouraged from using
* Make empty super() call in semverwithvprefix.py example
* Add changelog.d file
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -16,6 +16,59 @@ in our repository.
 
 .. towncrier release notes start
 
+Version 3.0.0-dev.2
+===================
+
+:Released: 2020-11-04
+:Maintainer:
+
+
+Improved Documentation
+----------------------
+
+* :gh:`312`: Rework "Usage" section.
+
+  * Mention the rename of :class:`~semver.version.VersionInfo` to
+    :class:`~semver.version.Version` class
+  * Remove semver. prefix in doctests to make examples shorter
+  * Correct some references to dunder methods like
+    :func:`~.semver.version.Version.__getitem__`,
+    :func:`~.semver.version.Version.__gt__` etc.
+  * Remove inconsistencies and mention module level function as
+    deprecated and discouraged from using
+  * Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example
+
+
+
+----
+
+
+Version 3.0.0-dev.2
+===================
+
+:Released: 2020-11-04
+:Maintainer:
+
+
+Improved Documentation
+----------------------
+
+* :gh:`312`: Rework "Usage" section.
+
+  * Mention the rename of :class:`~semver.version.VersionInfo` to
+    :class:`~semver.version.Version` class
+  * Remove semver. prefix in doctests to make examples shorter
+  * Correct some references to dunder methods like :func:`__getitem__`,
+    :func:`__gt__` etc.
+  * Remove inconsistencies and mention module level function as
+    deprecated and discouraged from using
+  * Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example
+
+
+
+----
+
+
 Version 3.0.0-dev.2
 ===================
 
diff --git a/changelog.d/312.doc.rst b/changelog.d/312.doc.rst
@@ -0,0 +1,11 @@
+Rework "Usage" section.
+
+* Mention the rename of :class:`~semver.version.VersionInfo` to
+  :class:`~semver.version.Version` class
+* Remove semver. prefix in doctests to make examples shorter
+* Correct some references to dunder methods like
+  :func:`~.semver.version.Version.__getitem__`,
+  :func:`~.semver.version.Version.__gt__` etc.
+* Remove inconsistencies and mention module level function as
+  deprecated and discouraged from using
+* Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example
diff --git a/docs/semverwithvprefix.py b/docs/semverwithvprefix.py
@@ -7,25 +7,22 @@ class SemVerWithVPrefix(Version):
     """
 
     @classmethod
-    def parse(cls, version):
+    def parse(cls, version: str) -> "SemVerWithVPrefix":
         """
         Parse version string to a Version instance.
 
         :param version: version string with "v" or "V" prefix
-        :type version: str
         :raises ValueError: when version does not start with "v" or "V"
         :return: a new instance
-        :rtype: :class:`SemVerWithVPrefix`
         """
         if not version[0] in ("v", "V"):
             raise ValueError(
                 "{v!r}: not a valid semantic version tag. Must start with 'v' or 'V'".format(
                     v=version
                 )
             )
-        self = super(SemVerWithVPrefix, cls).parse(version[1:])
-        return self
+        return super().parse(version[1:])
 
-    def __str__(self):
+    def __str__(self) -> str:
         # Reconstruct the tag
-        return "v" + super(SemVerWithVPrefix, self).__str__()
+        return "v" + super().__str__()
diff --git a/docs/usage.rst b/docs/usage.rst
