Merge pull request #1241 from ucb-bar/abejgonzalez-patch-1

Update stable docs

Author: abejgonzalez

docs/conf.py

@@ -66,17 +66,19 @@
 # built documents.
 
 on_rtd = os.environ.get("READTHEDOCS") == "True"
+on_gha = os.environ.get("GITHUB_ACTIONS") == "true"
+
 if on_rtd:
     for item, value in os.environ.items():
         print("[READTHEDOCS] {} = {}".format(item, value))
 
-# default to latest for non rtd builds (this will be overridden on rtd)
-rtd_version = "latest"
+# Come up with a short version string for the build. This is doing a bunch of lifting:
+# - format doc text that self-references its version (see title page). This may be used in an ad-hoc
+#   way to produce references to things like ScalaDoc, etc...
+# - procedurally generate github URL references using via `gh-file-ref`
 if on_rtd:
     rtd_version = os.environ.get("READTHEDOCS_VERSION")
-    if rtd_version == "latest":
-        version = "main" # TODO: default to what "latest" points to
-    elif rtd_version == "stable":
+    if rtd_version in ["stable", "latest"]:
         # get the latest git tag (which is what rtd normally builds under "stable")
         # this works since rtd builds things within the repo
         process = subprocess.Popen(["git", "describe", "--exact-match", "--tags"], stdout=subprocess.PIPE)
@@ -87,8 +89,23 @@
             version = "v?.?.?" # this should not occur as "stable" is always pointing to tagged version
     else:
         version = rtd_version # name of a branch
+elif on_gha:
+    # GitHub actions does a build of the docs to ensure they are free of warnings.
+    # Looking up a branch name or tag requires switching on the event type that triggered the workflow
+    # so just use the SHA of the commit instead.
+    version = os.environ.get("GITHUB_SHA")
+    rtd_version = "stable" # default to stable when not on rtd
 else:
-    version = "v?.?.?"
+    # When running locally, try to set version to a branch name that could be
+    # used to reference files on GH that could be added or moved. This should match rtd_version when running
+    # in a RTD build container
+    process = subprocess.Popen(["git", "rev-parse", "--abbrev-ref", "HEAD"], stdout=subprocess.PIPE)
+    output = process.communicate()[0].decode("utf-8").strip()
+    if process.returncode == 0:
+        version = output
+    else:
+        raise Exception("git rev-parse --abbrev-ref HEAD returned non-zero")
+    rtd_version = "stable" # default to stable when not on rtd
 
 # for now make these match
 release = version