fix(docs): Show latest released code on published site (#3716)

Our docs build script checks a `INCLUDE_RELEASED_CODE` env var to
determine what code snippets to include in the site build (either latest
released version or master). This should be set when deploying the site
to the public, which happens on every build on master. So we need to set
this env var when on master.

However, just setting the env var doesn't work, since we need to get it
inside the docs docker build context. Also, we need this build to be
seen as different than a build in a branch by the `check_rebuild`
script, even if they have the same content hash, since
`INCLUDE_RELEASED_CODE` affects the result.

One option for fixing this would've been adding a mechanism for passing
args to the `build` script in `build-system` which in turn passes them
as `ARG`s to the `docker build` call, so they can be turned into `ENV`
vars visible by our scripts. Another option could've been defining a
different `Dockerfile`, a `Dockerfile.master`, where this `ENV` var is
hardcoded. However, neither of these solves the `check_rebuild` issue.

So what we're doing is manually changing the contents of the `docs`
folder by writing a `.env` file with the env var we need to set, and
loading it when building. This both gets the env var inside the docker
context (since we're passing it in a file) and triggers a rebuild when
needed (since it changes the inputs used for calculating the content
hash).

Separately from the issues above, we need to manually fetch additional
commits from the repo, since we need to load code from the released
commit. We're doing that in the same step where we set up the `.env`,
which is after the checkout but before the build step.

While this approach seems to work, it is doing much stuff around
build-system, rather than playing along with it. So @charlielye I'd
appreciate your comments here before merging!

.circleci/config.yml

@@ -852,6 +852,13 @@ jobs:
       - run:
           name: "Copy docs dockerignore"
           command: cp docs/.dockerignore .
+      - run:
+          name: "Configure build for master"
+          command: |
+            if [ "$CIRCLE_BRANCH" == "master" ]; then
+              echo "Configuring build for master"
+              echo "INCLUDE_RELEASED_CODE=1" >> docs/.env
+            fi
       - run:
           name: "Build docs"
           command: build docs

docs/.gitignore

@@ -16,6 +16,7 @@
 .env.development.local
 .env.test.local
 .env.production.local
+.env
 
 npm-debug.log*
 yarn-debug.log*

docs/package.json

@@ -12,7 +12,7 @@
     "deploy": "docusaurus deploy",
     "clear": "rm -rf 'processed-docs' 'processed-docs-cache' docs/apis && docusaurus clear",
     "serve": "docusaurus serve",
-    "preprocess": "yarn node ./src/preprocess/index.js",
+    "preprocess": "yarn node -r dotenv/config ./src/preprocess/index.js",
     "preprocess:dev": "nodemon --config nodemon.json ./src/preprocess/index.js",
     "typedoc": "rm -rf docs/apis && docusaurus generate-typedoc && cp -a docs/apis processed-docs/",
     "typedoc:dev": "nodemon -w ../yarn-project -e '*.js,*.ts,*.nr,*.md' --exec \"rm -rf docs/apis && yarn docusaurus generate-typedoc && cp -a docs/apis processed-docs/\"",
@@ -40,6 +40,7 @@
     "@tsconfig/docusaurus": "^1.0.5",
     "concurrently": "^8.0.1",
     "docusaurus-plugin-typedoc": "^0.20.2",
+    "dotenv": "^16.3.1",
     "nodemon": "^3.0.1",
     "typedoc": "^0.25.1",
     "typedoc-plugin-markdown": "^3.16.0",

docs/yarn.lock

@@ -4043,6 +4043,11 @@ dot-prop@^5.2.0:
   dependencies:
     is-obj "^2.0.0"
 
+dotenv@^16.3.1:
+  version "16.3.1"
+  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-16.3.1.tgz#369034de7d7e5b120972693352a3bf112172cc3e"
+  integrity sha512-IPzF4w4/Rd94bA9imS68tZBaYyBWSCE47V1RGuMrB94iyTOIEwRmVL2x/4An+6mETpLrKJ5hQkB8W4kFAadeIQ==
+
 duplexer3@^0.1.4:
   version "0.1.5"
   resolved "https://registry.yarnpkg.com/duplexer3/-/duplexer3-0.1.5.tgz#0b5e4d7bad5de8901ea4440624c8e1d20099217e"