restore python code for doc versioning

Author: gilesknap

Pipfile

@@ -6,19 +6,15 @@ verify_ssl = true
 [dev-packages]
 # Pinning black stops us having to allow pre-releases globally
 black = "==19.10b0"
-
 # Pins to make lockfile usable on multiple Python versions and platforms
 mypy = "*"
 atomicwrites = "*"
 typing-extensions = "*"
 importlib-metadata = "*"
-
 # Switch to main repo after PR https://github.com/Holzhaus/sphinx-multiversion/pull/64 is merged
 sphinx-multiversion = {editable = true,git = "https://github.com/dls-controls/sphinx-multiversion.git",ref = "only-arg"}
-
 # List wheel here to make sure we make the same version to make wheels on gitlab and github CI
 wheel = "0.33.1"
-
 # Test and docs dependencies
 pytest-cov = "*"
 pytest-mypy = "*"
@@ -30,7 +26,7 @@ sphinx-rtd-theme = "*"
 
 [packages]
 # All other package requirements from setup.cfg
-k8s_epics_docs = {editable = true,path = "."}
+k8s_epics_docs = {editable = true, path = "."}
 
 [scripts]
 tests = "python -m pytest"

docs/conf.py

@@ -12,10 +12,8 @@
 import os
 import sys
 
-
 sys.path.insert(0, os.path.abspath(os.path.join(__file__, "..", "..")))
 
-import k8s_epics_docs  # noqa
 
 # -- General configuration ------------------------------------------------
 
@@ -30,7 +28,7 @@
 # The short X.Y version.
 if "+" in release:
     # Not on a tag
-    version = "master"
+    version = "main"
 else:
     version = release
 

k8s_epics_docs/__init__.py

@@ -0,0 +1,3 @@
+from k8s_epics_docs._version_git import __version__
+
+__all__ = ["__version__"]

k8s_epics_docs/__main__.py

@@ -0,0 +1,6 @@
+from k8s_epics_docs import cli
+
+# test with:
+#     pipenv run python -m k8s_epics_docs
+if __name__ == "__main__":
+    cli.main()

k8s_epics_docs/_version_git.py

@@ -0,0 +1,97 @@
+# Compute a version number from a git repo or archive
+
+# This file is released into the public domain. Generated by:
+# versiongit-1.0 (https://github.com/dls-controls/versiongit)
+import os
+import re
+import sys
+from subprocess import STDOUT, CalledProcessError, check_output
+
+# These will be filled in if git archive is run or by setup.py cmdclasses
+GIT_REFS = "$Format:%D$"
+GIT_SHA1 = "$Format:%h$"
+
+# Git describe gives us sha1, last version-like tag, and commits since then
+CMD = "git describe --tags --dirty --always --long --match=[0-9]*[-.][0-9]*"
+
+
+def get_version_from_git(path=None):
+    """Try to parse version from git describe, fallback to git archive tags"""
+    tag, plus, suffix = "0.0", "untagged", ""
+    if not GIT_SHA1.startswith("$"):
+        # git archive or the cmdclasses below have filled in these strings
+        sha1 = GIT_SHA1
+        for ref_name in GIT_REFS.split(", "):
+            if ref_name.startswith("tag: "):
+                # git from 1.8.3 onwards labels archive tags "tag: TAGNAME"
+                tag, plus = ref_name[5:], "0"
+    else:
+        if path is None:
+            # If no path to git repo, choose the directory this file is in
+            path = os.path.dirname(os.path.abspath(__file__))
+        # output is TAG-NUM-gHEX[-dirty] or HEX[-dirty]
+        try:
+            cmd_out = check_output(CMD.split(), stderr=STDOUT, cwd=path)
+        except Exception as e:
+            sys.stderr.write("%s: %s\n" % (type(e).__name__, str(e)))
+            if isinstance(e, CalledProcessError):
+                sys.stderr.write("-> %s" % e.output.decode())
+            return "0.0+unknown", None, e
+        else:
+            out = cmd_out.decode().strip()
+            if out.endswith("-dirty"):
+                out = out[:-6]
+                suffix = ".dirty"
+            if "-" in out:
+                # There is a tag, extract it and the other pieces
+                match = re.search(r"^(.+)-(\d+)-g([0-9a-f]+)$", out)
+                tag, plus, sha1 = match.groups()
+            else:
+                # No tag, just sha1
+                sha1 = out
+    # Replace dashes in tag for dots
+    tag = tag.replace("-", ".")
+    if plus != "0" or suffix:
+        # Not on a tag, add additional info
+        tag = "%(tag)s+%(plus)s.g%(sha1)s%(suffix)s" % locals()
+    return tag, sha1, None
+
+
+__version__, git_sha1, git_error = get_version_from_git()
+
+
+def get_cmdclass(build_py=None, sdist=None):
+    """Create cmdclass dict to pass to setuptools.setup that will write a
+    _version_static.py file in our resultant sdist, wheel or egg"""
+    if build_py is None:
+        from setuptools.command.build_py import build_py
+    if sdist is None:
+        from setuptools.command.sdist import sdist
+
+    def make_version_static(base_dir, pkg):
+        vg = os.path.join(base_dir, pkg.split(".")[0], "_version_git.py")
+        if os.path.isfile(vg):
+            lines = open(vg).readlines()
+            with open(vg, "w") as f:
+                for line in lines:
+                    # Replace GIT_* with static versions
+                    if line.startswith("GIT_SHA1 = "):
+                        f.write("GIT_SHA1 = '%s'\n" % git_sha1)
+                    elif line.startswith("GIT_REFS = "):
+                        f.write("GIT_REFS = 'tag: %s'\n" % __version__)
+                    else:
+                        f.write(line)
+
+    class BuildPy(build_py):
+        def run(self):
+            build_py.run(self)
+            for pkg in self.packages:
+                make_version_static(self.build_lib, pkg)
+
+    class Sdist(sdist):
+        def make_release_tree(self, base_dir, files):
+            sdist.make_release_tree(self, base_dir, files)
+            for pkg in self.distribution.packages:
+                make_version_static(base_dir, pkg)
+
+    return dict(build_py=BuildPy, sdist=Sdist)

k8s_epics_docs/cli.py

@@ -0,0 +1,11 @@
+from argparse import ArgumentParser
+
+from k8s_epics_docs import __version__
+
+
+def main(args=None):
+    parser = ArgumentParser()
+    parser.add_argument("--version", action="version", version=__version__)
+    args = parser.parse_args(args)
+
+    # dummy CLI entry point

setup.cfg

@@ -0,0 +1,40 @@
+[metadata]
+name = k8s_epics_docs
+description = One line description of your module
+url = https://github.com/epics-containers/k8s_epics_docs
+author = Giles Knap
+author_email = [email protected]
+license = Apache License 2.0
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+classifiers =
+    Development Status :: 4 - Beta
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+
+[options]
+packages = find:
+# install_requires =
+#     numpy
+#     scipy
+
+# If you want to include data files in packages,
+# either define [options.package_data] or
+# set this to True and include a MANIFEST.in file.
+include_package_data = False
+
+[options.packages.find]
+# Don't include our tests directory in the distribution
+exclude = tests
+
+[tool:pytest]
+# Run pytest with all our checkers, and don't spam us with massive tracebacks on error
+addopts =
+    --tb=native -vv --flake8 --black --mypy --doctest-modules --doctest-glob="*.rst"
+     --cov=k8s_epics_docs --cov-report term --cov-report xml:cov.xml
+
+[coverage:run]
+# This is covered in the versiongit test suite so exclude it here
+omit = */_version_git.py

setup.py

@@ -0,0 +1,17 @@
+import os
+import sys
+
+from setuptools import setup
+
+
+# Place the directory containing _version_git on the path
+for path, _, filenames in os.walk(os.path.dirname(os.path.abspath(__file__))):
+    if "_version_git.py" in filenames:
+        sys.path.append(path)
+        break
+
+from _version_git import __version__, get_cmdclass  # noqa
+
+# Setup information is stored in setup.cfg but this function call
+# is still necessary.
+setup(cmdclass=get_cmdclass(), version=__version__)