Merge pull request #1931 from ucb-bar/update-docs

Update docs

.github/workflows/weekly-tag.yml

@@ -0,0 +1,31 @@
+name: weekly-tag
+
+on: workflow_dispatch
+
+defaults:
+  run:
+    shell: bash -leo pipefail {0}
+
+jobs:
+  tagger:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Get latest semver tag, add +1 to minor version (drop patch), generate tag for it
+        run: |
+          NEWSEMVER=$(echo $(git describe --abbrev=0 --tags) | awk -F'[.]'  '{
+          major=$1;
+          minor=$2;
+          minor += 1;
+          printf( "%d.%d.0\n", major, minor );
+          }')
+          echo "Tagging with $NEWSEMVER"
+          curl --request POST \
+            --url https://api.github.com/repos/${{ github.repository }}/git/refs \
+            --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
+            --data @- << EOF
+          {
+            "ref": "refs/tags/$NEWSEMVER",
+            "sha": "${{ github.sha }}"
+          }
+          EOF

README.md

@@ -4,13 +4,13 @@
 
 ## Quick Links
 
-* **Stable Documentation**: https://chipyard.readthedocs.io/
+* **Latest Documentation**: https://chipyard.readthedocs.io/
 * **User Question Forum**: https://groups.google.com/forum/#!forum/chipyard
 * **Bugs and Feature Requests**: https://github.com/ucb-bar/chipyard/issues
 
 ## Using Chipyard
 
-To get started using Chipyard, see the stable documentation on the Chipyard documentation site: https://chipyard.readthedocs.io/
+To get started using Chipyard, see the documentation on the Chipyard documentation site: https://chipyard.readthedocs.io/
 
 ## What is Chipyard
 
@@ -22,7 +22,7 @@ Chipyard is actively developed in the [Berkeley Architecture Research Group][ucb
 
 ## Resources
 
-* Chipyard Stable Documentation: https://chipyard.readthedocs.io/
+* Chipyard Documentation: https://chipyard.readthedocs.io/
 * Chipyard (x FireSim) Tutorial: https://fires.im/tutorial-recent/
 * Chipyard Basics slides: https://fires.im/asplos23-slides-pdf/02_chipyard_basics.pdf
 

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

@@ -9,7 +9,7 @@ Chipyard is developed and tested on Linux-based systems.
 .. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed;
     it is also recommended to install the RISC-V toolchain from ``brew``.
 
-.. Warning:: If using Windows, it is recommended that you use `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/> (WSL)`.
+.. Warning:: If using Windows, it is recommended that you use `Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/>`.
 
 Running on AWS EC2 with FireSim
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/conf.py

@@ -72,40 +72,62 @@
     for item, value in os.environ.items():
         print("[READTHEDOCS] {} = {}".format(item, value))
 
+def get_git_tag():
+    # 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)
+    tag = process.communicate()[0].decode("utf-8").strip()
+    if process.returncode == 0:
+        return tag
+    else:
+        return None
+
+def get_git_branch_name():
+    # 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)
+    branchname = process.communicate()[0].decode("utf-8").strip()
+    if process.returncode == 0:
+        return branchname
+    else:
+        return None
+
 # 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`
+#   - 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`
+#
+# For Chipyard, the RTD version can be multiple things:
+#   1. 'stable' - This points to a branch called 'stable' in the repo. that was previously manually updated each release. This is outdated.
+#   2. 'latest' - This points to the 'main' branch documentation. This is recommended.
+#   3. '<another-branch-name>' - This points to a branch. Normally used for testing if a branches documentation builds.
 if on_rtd:
     rtd_version = os.environ.get("READTHEDOCS_VERSION")
-    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)
-        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
+    if rtd_version == "latest":
+        branchname = get_git_branch_name()
+        assert branchname is not None
+        version = branchname
+    elif rtd_version == "stable":
+        tag = get_git_tag()
+        assert tag is not None
+        version = tag
     else:
-        version = rtd_version # name of a branch
+        version = rtd_version # should be name of a branch
 elif on_gha:
+    rtd_version = "latest"
     # 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:
+    rtd_version = "latest"
     # 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
+    branchname = get_git_branch_name()
+    assert branchname is not None
+    version = branchname
 
 # for now make these match
 release = version