diff --git a/.readthedocs.yml b/.readthedocs.yml
index 43e2d306..51959f5a 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,16 @@
 version: 2
+
+build:
+    os: ubuntu-20.04
+    tools:
+        python: "3.6"
+
 formats: all
+
 sphinx:
-  configuration: docs/conf.py
+    configuration: docs/conf.py
+    fail_on_warning: true
+
 python:
-   install:
-      - requirements: docs/requirements.txt
+    install:
+        - requirements: docs/requirements.txt
diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst
index 93e12ca6..2638d852 100644
--- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst
+++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst
@@ -29,12 +29,13 @@ 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
-    # fancy way to checkout latest tag (for example resolves to "1.5.0" if that is the latest)                   │ 31 -------------------------------------------
-    git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
+    # 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.
diff --git a/docs/conf.py b/docs/conf.py
index f78001c8..acf781f5 100644
--- a/docs/conf.py
+++ b/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 ---------------------------------------------
 
diff --git a/docs/index.rst b/docs/index.rst
index 3e0db05a..48791642 100644
--- a/docs/index.rst
+++ b/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
 
diff --git a/scripts/init-submodules-no-riscv-tools-nolog.sh b/scripts/init-submodules-no-riscv-tools-nolog.sh
index 9d98e6f2..86420ac6 100755
--- a/scripts/init-submodules-no-riscv-tools-nolog.sh
+++ b/scripts/init-submodules-no-riscv-tools-nolog.sh
@@ -52,12 +52,12 @@ tag_ret_code=$?
 set -e
 if [ $tag_ret_code -ne 0 ]; then
     if [ "$SKIP_VALIDATE" = false ]; then
-        read -p "WARNING: You are not on a tagged release of Chipyard. Type \"ok\" to continue: " validate
-        [[ $validate == [oO][kK] ]] || exit 3
-        echo "Setting up non-release Chipyard"
+        read -p "WARNING: You are not on an official release of Chipyard.\nType \"y\" to continue if this is intended, otherwise see https://chipyard.readthedocs.io/en/stable/Chipyard-Basics/Initial-Repo-Setup.html#setting-up-the-chipyard-repo: " validate
+        [[ $validate == [yY] ]] || exit 3
+        echo "Setting up non-official Chipyard release"
     fi
 else
-    echo "Setting up Chipyard $tag"
+    echo "Setting up official Chipyard release: $tag"
 fi
 
 # On macOS, use GNU readlink from 'coreutils' package in Homebrew/MacPorts