Automated RST tutorial

.github/workflows/chipyard-tutorials.yml

@@ -27,6 +27,7 @@ jobs:
         with:
           access_token: ${{ github.token }}
 
+  # example of running a tutorial given a pre-made script
   first-verilog-build-tutorial:
     name: First Verilog Build Tutorial
     needs: [cancel-prior-workflows]
@@ -44,7 +45,6 @@ jobs:
         run: |
           git clone ${{ github.workspace }} $CHIPYARD_DIR
           mkdir $JAVA_TMP_DIR
-      # TODO: should/could be autogenerated from the docs
       # a script with all the tutorial commands
       - name: Run tutorial
         run: |
@@ -55,3 +55,35 @@ jobs:
         run: |
           rm -rf ${{ env.REMOTE_WORK_DIR }}
           rm -rf ${{ env.JAVA_TMP_DIR }}
+
+  # example of running a tutorial from an auto-generated script built from .rst
+  first-verilog-build-automated-tutorial:
+    name: First Verilog Build Automated Tutorial
+    needs: [cancel-prior-workflows]
+    runs-on: as4
+    steps:
+      # workaround actions/checkout not 'cleaning' submodules on new checkouts. see https://github.com/actions/checkout/issues/358
+      - name: Delete old checkout
+        run: |
+          rm -rf ${{ github.workspace }}/* || true
+          rm -rf ${{ github.workspace }}/.* || true
+      - uses: actions/checkout@v3
+      # copy repository to globally visible area (useful for if tutorials need to be split across multiple GH-A jobs).
+      # in this case, a tutorial run is within a single GH-A job so you could just use the $GITHUB_WORKSPACE
+      - name: Setup repository
+        run: |
+          git clone ${{ github.workspace }} $CHIPYARD_DIR
+          mkdir $JAVA_TMP_DIR
+      # run the autogenerated script with all the tutorial commands
+      - name: Run tutorial
+        run: |
+          cd $CHIPYARD_DIR # cd's into globally visible directory 1st (otherwise would run out of the $GITHUB_WORKSPACE which is per-job)
+          scripts/generate-script-from-tutorial-rst.py docs/Tutorials/First-Verilog-Build.rst tutorial.sh
+          echo "Created tutorial.sh >>>" && cat tutorial.sh && echo "<<< Done tutorial.sh"
+          chmod +x tutorial.sh
+          ./tutorial.sh
+      - name: Delete repository (and other misc. data)
+        if: ${{ always() }} # always run at the end
+        run: |
+          rm -rf ${{ env.REMOTE_WORK_DIR }}
+          rm -rf ${{ env.JAVA_TMP_DIR }}

docs/Tutorials/First-Verilog-Build.rst

@@ -0,0 +1,39 @@
+First Verilog Build
+===================
+
+This tutorial guides you through setting up Chipyard for the first time and building Verilog (specifically a Rocket core SoC).
+
+.. code-block:: shell
+
+    cd $CHIPYARD_DIR
+
+.. only:: replace-code-above
+
+    cd $CHIPYARD_DIR
+    export MAKEFLAGS="-j32"
+
+.. code-block:: shell
+
+    ./build-setup.sh
+
+.. only:: replace-code-above
+
+    ./build-setup.sh -f -v
+
+.. code-block:: shell
+
+    source env.sh
+
+.. code-block:: shell
+
+    cd sims/verilator
+    make verilog
+
+.. code-block:: shell
+
+    make
+
+.. code-block:: shell
+
+    ls -alh generated-src
+    ls -alh simulator*

docs/Tutorials/index.rst

@@ -0,0 +1,13 @@
+Tutorials
+================
+
+This section holds various tutorials for specific features, workflows, and more within Chipyard.
+Each requires you to checkout the Chipyard repo and set the ``CHIPYARD_DIR`` environment variable before continuing on.
+
+.. Warning:: Tutorials are only guaranteed to work on released versions of Chipyard.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials:
+
+   First-Verilog-Build

docs/index.rst

@@ -43,6 +43,8 @@ Table of Contents
 
    Prototyping/index
 
+   Tutorials/index
+
 
 Indices and tables
 ==================

scripts/generate-script-from-tutorial-rst.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+import sys
+
+# $1 - rst file to parse
+# $2 - output bash file to write
+
+if len(sys.argv) != 3:
+    sys.exit("[ERROR] Incorrect # of args.")
+
+rstFile = sys.argv[1]
+bashFile = sys.argv[2]
+
+codeBlocks = [] # ordered list of blocks, each block is (type: String, lines: List[Strings])
+
+with open(rstFile, 'r') as rstF:
+    inBlock = False
+    skipEmpty = False
+    curBlockType = ""
+    curBlockLines = []
+    for line in rstF.readlines():
+        if inBlock:
+            if len(line) == 1 and line == '\n':
+                # empty line
+                if not skipEmpty:
+                    # empty line (done with block)
+                    inBlock = False
+                    codeBlocks.append((curBlockType, curBlockLines))
+                    curBlockType = ""
+                    curBlockLines = []
+                skipEmpty = False
+            else:
+                assert (line[0:4] == ' ' * 4), "Must only strip whitespace (ensure RST only has 4 spaces before code lines)"
+                curBlockLines.append(line[4:]) # strip the first 4 spaces (indent)
+        else:
+            if ".. code-block:: shell" in line:
+                inBlock = True
+                curBlockType = "code-block"
+                skipEmpty = True
+            elif ".. only:: replace-code-above" in line:
+                inBlock = True
+                curBlockType = "replace-above"
+                skipEmpty = True
+
+idxToDelete = []
+for idx, cb in enumerate(codeBlocks):
+    if cb[0] == "replace-above":
+        idxToDelete.append(idx)
+
+# TODO: could check that replace-code-above directives cannot follow one another
+
+idxToDelete.reverse()
+for idx in idxToDelete:
+    assert idx - 1 >= 0, "replace-code-above directives must come after a code-block directive"
+    codeBlocks.pop(idx - 1)
+
+with open(bashFile, 'w') as bashF:
+    header = """#!/usr/bin/env bash
+
+# exit script if any command fails
+set -e
+set -o pipefail
+
+# $CHIPYARD_DIR should be defined and pointing to the top-level folder in Chipyard
+if [[ -z "${CHIPYARD_DIR}" ]]; then
+  echo "Environment variable \$CHIPYARD_DIR is undefined. Unable to run script."
+  exit 1
+fi
+"""
+    bashF.writelines([header, '\n'])
+    for cb in codeBlocks:
+        bashF.writelines(cb[1])