Merge remote-tracking branch 'origin/dev' into dev-sky130 [ci skip]

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -29,13 +29,17 @@ Setting up the Chipyard Repo
 
 Start by fetching Chipyard's sources. Run:
 
-.. code-block:: shell
+.. parsed-literal::
 
     git clone https://github.com/ucb-bar/chipyard.git
     cd chipyard
+    # checkout latest official chipyard release
+    # note: this may not be the latest release if the documentation version != "stable"
+    git checkout |version|
     ./scripts/init-submodules-no-riscv-tools.sh
 
 This will initialize and checkout all of the necessary git submodules.
+This will also validate that you are on a tagged branch, otherwise it will prompt for confirmation.
 
 When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
 Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.

docs/conf.py

@@ -20,6 +20,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import subprocess
 
 # -- General configuration ------------------------------------------------
 
@@ -59,11 +61,32 @@ author = u'Berkeley Architecture Research'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = u''
-# The full version, including alpha/beta/rc tags.
-release = u''
+
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+if on_rtd:
+    for item, value in os.environ.items():
+        print("[READTHEDOCS] {} = {}".format(item, value))
+
+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":
+        # 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)
+        output = process.communicate()[0].decode("utf-8").strip()
+        if process.returncode == 0:
+            version = output
+        else:
+            version = "v?.?.?" # this should not occur as "stable" is always pointing to tagged version
+    else:
+        version = rtd_version # name of a branch
+else:
+    version = "v?.?.?"
+
+# for now make these match
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -132,6 +155,17 @@ html_logo = '_static/images/chipyard-logo.png'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Chipyarddoc'
 
+# -- Misc Options ---------------------------------------------------------
+
+html_context = {
+    "version": version
+}
+
+# add rst to end of each rst source file
+# can put custom strings here that are generated from this file
+rst_epilog = f"""
+.. |overall_version| replace:: {version}
+"""
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -1,10 +1,5 @@
-.. Chipyard documentation master file, created by
-   sphinx-quickstart on Fri Mar  8 11:46:38 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Chipyard's documentation!
-====================================
+Welcome to Chipyard's documentation (version "|version|")!
+==========================================================
 
 .. image:: ./_static/images/chipyard-logo.svg