From f1eb6d5b6e3221e5a5b8f55632dba066d4cfbc24 Mon Sep 17 00:00:00 2001 From: Santiago Palladino Date: Wed, 20 Dec 2023 07:40:12 -0300 Subject: [PATCH] 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 | 7 +++++++ docs/.gitignore | 1 + docs/package.json | 3 ++- docs/yarn.lock | 5 +++++ 4 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index a9cf73da295..31bb8ce214c 100644 --- a/.circleci/config.yml +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore index 0e0b92f6647..462844ee8bd 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -16,6 +16,7 @@ .env.development.local .env.test.local .env.production.local +.env npm-debug.log* yarn-debug.log* diff --git a/docs/package.json b/docs/package.json index 6b3883f2282..134ded2a6c7 100644 --- a/docs/package.json +++ b/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", diff --git a/docs/yarn.lock b/docs/yarn.lock index 5610f57dfe4..3ac7b7d4c22 100644 --- a/docs/yarn.lock +++ b/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"