Improve API documentation

tomschr · tomschr · commit 7d00884712af · 2020-11-01T16:14:08.000+01:00
* Use sphinx-apidoc to build API documentation * Amend tox.ini and call sphinx-apidoc * Remove old autosummary; it turned out it was difficult to configure and returned warning messages which were hard to fix. * Add semver version in footer * Add semver.__about__ to API doc * Unorthodox solution with sed * Remove obsolete config variables in docs/config.py * Add docs/_api/semver.__about__.rst as a placeholder * Add changelog.d/304.doc.rst (An old attempt was to use autosummary from https://stackoverflow.com/a/62613202; however, that didn't work quite well.) Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com>
diff --git a/.gitignore b/.gitignore
@@ -259,7 +259,8 @@ fabric.properties
 # --------
 
 
-
 # Patch/Diff Files
 *.patch
 *.diff
+docs/_api
+!docs/_api/semver.__about__.rst
diff --git a/changelog.d/304.doc.rst b/changelog.d/304.doc.rst
@@ -0,0 +1,5 @@
+Several improvements in documentation:
+
+* Reorganize API documentation.
+* Add migration chapter from semver2 to semver3.
+* Distinguish between changlog for version 2 and 3
diff --git a/docs/_api/semver.__about__.rst b/docs/_api/semver.__about__.rst
@@ -0,0 +1,5 @@
+semver.\_\_about\_\_ module
+===========================
+
+.. automodule:: semver.__about__
+   :members:
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -26,6 +26,11 @@ div.related.top nav {
     margin-top: 0.5em;
 }
 
+.sphinxsidebarwrapper .caption {
+    margin-top: 1em;
+    margin-bottom: -0.75em;
+}
+
 .section h1 {
     font-weight: 700;
 }
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -2,3 +2,48 @@
   Import the theme's layout.
 #}
 {% extends "!layout.html" %}
+
+{%- block footer %}
+<div class="footer">
+<p>
+  {% if show_copyright %}&copy;{{ copyright }}.{% endif %}
+  {% if theme_show_powered_by|lower == 'true' %}
+  {% if show_copyright %}|{% endif %}
+  {% if show_copyright %}|{% endif %}
+    Powered by <a href="http://sphinx-doc.org/">Sphinx {{ sphinx_version }}</a>
+    &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster {{ alabaster_version }}</a>
+  {% endif %}
+  {%- if show_source and has_source and sourcename %}
+  {% if show_copyright or theme_show_powered_by %}|{% endif %}
+  <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+          rel="nofollow">{{ _('Page source') }}</a>
+  {%- endif %}
+</p>
+<p>
+  For <a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}"
+  >semver {{ version }}</a>
+</p>
+</div>
+
+{% if theme_github_banner|lower != 'false' %}
+<a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}" class="github">
+    <img style="position: absolute; top: 0; right: 0; border: 0;" src="{{ pathto('_static/' ~ theme_github_banner, 1) if theme_github_banner|lower != 'true' else 'https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png' }}" alt="Fork me on GitHub"  class="github"/>
+</a>
+{% endif %}
+{% if theme_analytics_id %}
+<script type="text/javascript">
+
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', '{{ theme_analytics_id }}']);
+  _gaq.push(['_setDomainName', 'none']);
+  _gaq.push(['_setAllowLinker', true]);
+  _gaq.push(['_trackPageview']);
+
+  (function() {
+    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+  </script>
+{% endif %}
+{%- endblock %}
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,8 +1,10 @@
 .. _api:
 
+###
 API
-===
+###
 
-.. automodule:: semver
-   :members:
-   :undoc-members:
+.. toctree::
+   :maxdepth: 4
+
+   _api/semver
diff --git a/docs/coerce.py b/docs/coerce.py
@@ -1,5 +1,7 @@
 import re
-import semver
+from semver import Version
+from typing import Optional, Tuple
+
 
 BASEVERSION = re.compile(
     r"""[vV]?
@@ -15,7 +17,7 @@
 )
 
 
-def coerce(version):
+def coerce(version: str) -> Tuple[Version, Optional[str]]:
     """
     Convert an incomplete version string into a semver-compatible Version
     object
@@ -37,6 +39,6 @@ def coerce(version):
     ver = {
         key: 0 if value is None else value for key, value in match.groupdict().items()
     }
-    ver = semver.Version(**ver)
+    ver = Version(**ver)
     rest = match.string[match.end() :]  # noqa:E203
     return ver, rest
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,12 +16,35 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import codecs
 import os
+import re
 import sys
 
 sys.path.insert(0, os.path.abspath("../src/"))
+# from semver import __version__  # noqa: E402
 
-from semver import __version__  # noqa: E402
+
+def read(*parts):
+    """
+    Build an absolute path from *parts* and and return the contents of the
+    resulting file.  Assume UTF-8 encoding.
+    """
+    here = os.path.abspath(os.path.dirname(__file__))
+    with codecs.open(os.path.join(here, *parts), "rb", "utf-8") as f:
+        return f.read()
+
+
+def find_version(*file_paths):
+    """
+    Build a path from *file_paths* and search for a ``__version__``
+    string inside.
+    """
+    version_file = read(*file_paths)
+    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file, re.M)
+    if version_match:
+        return version_match.group(1)
+    raise RuntimeError("Unable to find version string.")
 
 
 # -- General configuration ------------------------------------------------
@@ -35,12 +58,16 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.napoleon",
     "sphinx.ext.extlinks",
 ]
 
+autoclass_content = "class"
+autodoc_default_options = {}
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -62,16 +89,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = __version__
+release = find_version("../src/semver/__about__.py")
 # The full version, including alpha/beta/rc tags.
-release = version
+version = release  # .rsplit(u".", 1)[0]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/docs/readme.rst b/docs/readme.rst
@@ -1,2 +1,4 @@
-.. include:: ../README.rst
+If you are searching for how to stay compatible
+with semver3, refer to :ref:`semver2-to-3`.
 
+.. include:: ../README.rst
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -89,7 +89,7 @@ A :class:`semver.Version` instance can be created in different ways:
       ValueError: 'major' is negative. A version can only be positive.
 
     As a minimum requirement, your dictionary needs at least the
-  be positive.
+    be positive.
 
     >>> semver.Version(-1)
     Traceback (most recent call last):
diff --git a/src/semver/__about__.py b/src/semver/__about__.py
@@ -1,8 +1,29 @@
+"""
+Metadata about semver.
+
+Contains information about semver's version, the implemented version
+of the semver specifictation, author, maintainers, and description.
+
+.. autodata:: __version__
+"""
+
+#: Semver version
 __version__ = "3.0.0-dev.2"
+
+#: Original semver author
 __author__ = "Kostiantyn Rybnikov"
+
+#: Author's email address
 __author_email__ = "k-bx@k-bx.com"
+
+#: Current maintainer
 __maintainer__ = ["Sebastien Celles", "Tom Schraitle"]
+
+#: Maintainer's email address
 __maintainer_email__ = "s.celles@gmail.com"
+
+#: Short description about semver
 __description__ = "Python helper for Semantic Versioning (http://semver.org)"
 
+#: Supported semver specification
 SEMVER_SPEC_VERSION = "2.0.0"
diff --git a/src/semver/__init__.py b/src/semver/__init__.py
@@ -1,3 +1,9 @@
+"""
+semver package major release 3.
+
+A Python module for semantic versioning. Simplifies comparing versions.
+"""
+
 from ._deprecated import (
     bump_build,
     bump_major,
diff --git a/src/semver/__main__.py b/src/semver/__main__.py
@@ -1,8 +1,13 @@
 """
 Module to support call with :file:`__main__.py`. Used to support the following
-call:
+call::
+
+    $ python3 -m semver ...
+
+This makes it also possible to "run" a wheel like in this command::
+
+    $ python3 semver-3*-py3-none-any.whl/semver -h
 
-$ python3 -m semver ...
 """
 import os.path
 import sys
diff --git a/src/semver/_deprecated.py b/src/semver/_deprecated.py
@@ -1,3 +1,8 @@
+"""
+Contains all deprecated functions.
+
+.. autofunction: deprecated
+"""
 import inspect
 import warnings
 from functools import partial, wraps
@@ -102,8 +107,10 @@ def parse_version_info(version):
        Use :func:`semver.VersionInfo.parse` instead.
     .. versionadded:: 2.7.2
        Added :func:`semver.parse_version_info`
+
     :param version: version string
     :return: a :class:`VersionInfo` instance
+
     >>> version_info = semver.Version.parse("3.4.5-pre.2+build.4")
     >>> version_info.major
     3
@@ -356,11 +363,13 @@ def replace(version, **parts):
        Use :func:`semver.Version.replace` instead.
     .. versionadded:: 2.9.0
        Added :func:`replace`
+
     :param version: the version string to replace
     :param parts: the parts to be updated. Valid keys are:
       ``major``, ``minor``, ``patch``, ``prerelease``, or ``build``
     :return: the replaced version string
     :raises TypeError: if ``parts`` contains invalid keys
+
     >>> import semver
     >>> semver.replace("1.2.3", major=2, patch=10)
     '2.2.10'
diff --git a/src/semver/cli.py b/src/semver/cli.py
@@ -1,3 +1,5 @@
+"""CLI parsing for :command:`pysemver` command."""
+
 import argparse
 import sys
 from typing import cast, List
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -1,3 +1,5 @@
+"""Version handling."""
+
 import collections
 import re
 from functools import wraps
@@ -414,7 +416,7 @@ def next_version(self, part: str, prerelease_token: str = "rc") -> "Version":
         The "major", "minor", and "patch" raises the respective parts like
         the ``bump_*`` functions. The real difference is using the
         "preprelease" part. It gives you the next patch version of the
-         prerelease, for example:
+        prerelease, for example:
 
         >>> str(semver.parse("0.1.4").next_version("prerelease"))
         '0.1.5-rc.1'
@@ -550,6 +552,7 @@ def match(self, match_expr: str) -> bool:
               ==  equal
               !=  not equal
         :return: True if the expression matches the version, otherwise False
+
         >>> semver.Version.parse("2.0.0").match(">=1.0.0")
         True
         >>> semver.Version.parse("1.0.0").match(">1.0.0")
@@ -591,9 +594,11 @@ def parse(cls, version: String) -> "Version":
         .. versionchanged:: 2.11.0
            Changed method from static to classmethod to
            allow subclasses.
+
         :param version: version string
         :return: a :class:`VersionInfo` instance
         :raises ValueError: if version is invalid
+
         >>> semver.Version.parse('3.4.5-pre.2+build.4')
         VersionInfo(major=3, minor=4, patch=5, \
 prerelease='pre.2', build='build.4')
@@ -651,5 +656,5 @@ def isvalid(cls, version: str) -> bool:
             return False
 
 
-# Keep the VersionInfo name for compatibility
+#: Keep the VersionInfo name for compatibility
 VersionInfo = Version
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -12,6 +12,7 @@
 
 @pytest.fixture(autouse=True)
 def add_semver(doctest_namespace):
+    doctest_namespace["Version"] = semver.Version
     doctest_namespace["semver"] = semver
     doctest_namespace["coerce"] = coerce
     doctest_namespace["SemVerWithVPrefix"] = SemVerWithVPrefix
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,11 @@ div.related.top nav {`
`26`	`26`	`margin-top: 0.5em;`
`27`	`27`	`}`
`28`	`28`
	`29`	`+.sphinxsidebarwrapper .caption {`
	`30`	`+ margin-top: 1em;`
	`31`	`+ margin-bottom: -0.75em;`
	`32`	`+}`
	`33`	`+`
`29`	`34`	`.section h1 {`
`30`	`35`	`font-weight: 700;`
`31`	`36`	`}`