feat(docs): versioned documentation between HEAD and release (#470)

* wip improved website

* work on versioning

* try swizzling version dropdown

* swizzle version link

* push latest docs

* revert to the original workspace config

* use substrate workspace plugin (#472)

* feat(release): use cargo workspace plugin (#473)

* use substrate workspace plugin

* fix examples

* Add examples to release please

* fix versioning

* try removing comments

* test release pleaes features

* complete doc changes for release vs latest

* fix examples paths

* cleanup pr

* try creating workflows for deploying docs

* test actions

* get workflow registered

* try again to get workflow registered

* remove extraneous dependencies

* remove docs usage

* temporarily use main environment

* try again

* test

* fix deploy docs action

* add back checkoutv3

* finalize docs deploy strategy

* fix copy

* try removing substrate api examples until it compiles

* try rerunning CI-main

* undo

* extract deployment to bash scripts

* make scripts executable

* fix variable usage

* fix argument parsing

* fix globs

* support branch docs

* fix deploy script

* fix deploy script

* migrate to docusaurus 3.7 and fix deploy script

* modify site-config.json in deploy

* fix heredoc usage

* test api doc deploy

* remove push CI

* fix api deploy script

* clean up workflow yaml

* remove iarna toml

.github/workflows/check-workspace.yml

@@ -35,7 +35,7 @@ jobs:
           RUSTDOCFLAGS: '-D warnings'
   test:
     name: test
-    runs-on: [bwrc, nfs]
+    runs-on: bwrc
     steps:
       - uses: actions/checkout@v3
       - name: Test

.github/workflows/ci-main.yml

@@ -1,4 +1,4 @@
-name: CI
+name: ci-main
 
 on:
   push:
@@ -26,7 +26,9 @@ jobs:
         with:
           repository: rohanku/release-please
           path: release-please
-          ref: dev
+          # Can change back to `dev` once this is merged into Substrate `main` and 
+          # the release-please `substrate-workspace` branch is merged into `dev`.
+          ref: substrate-workspace
       - uses: actions/setup-node@v3
         with:
           node-version: 18
@@ -84,38 +86,7 @@ jobs:
         working-directory: substrate
         run: ../cargo-workspaces/cargo-workspaces/target/debug/cargo-ws workspaces publish --from-git --token=${{ secrets.KTRA_TOKEN }} --registry=substrate --yes --allow-dirty
   deploy-api-docs:
-    name: Deploy API documentation
-    runs-on: bwrc
-    environment: main
-    needs: [ check-workspace ]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: superfly/flyctl-actions/setup-flyctl@ddcac349402ef55840d9870785f4df1890768078
-      - run: just build
-        working-directory: docs/api
-      - run: flyctl deploy --remote-only --detach
-        working-directory: docs/api
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_API }}
+    uses: ./.github/workflows/deploy-api-docs.yml
   deploy-docs:
-    name: Deploy documentation
-    runs-on: ubuntu-22.04
-    environment: main
-    needs: [ check-workspace ]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: superfly/flyctl-actions/setup-flyctl@master
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: 'yarn'
-          cache-dependency-path: docs/site/yarn.lock
-      - run: yarn install
-        working-directory: docs/site
-      - run: yarn build 
-        working-directory: docs/site
-      - run: flyctl deploy --remote-only --detach
-        working-directory: docs/site
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_DOCS }}
+    uses: ./.github/workflows/deploy-docs.yml
 

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI
+name: ci
 
 on:
   pull_request:

.github/workflows/deploy-api-docs.yml

@@ -0,0 +1,25 @@
+name: deploy-api-docs
+
+on:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      name:
+
+env:
+    CARGO_TERM_COLOR: always
+    DOCS_NAME: ${{ inputs.name || github.ref.name }}
+    PUBLIC_DOCS_DIR: /Users/rohan/Downloads/substrate_docs_public
+
+jobs:
+  deploy-api-docs:
+    name: Deploy API documentation
+    runs-on: bwrc
+    environment: docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: superfly/flyctl-actions/setup-flyctl@ddcac349402ef55840d9870785f4df1890768078
+      - run: ./deploy.sh ${{ env.PUBLIC_DOCS_DIR }} ${{ inputs.name || github.ref_name }}
+        working-directory: docs/api
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_API }}

.github/workflows/deploy-docs.yml

@@ -0,0 +1,31 @@
+name: deploy-docs
+
+on:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      name:
+
+env:
+    CARGO_TERM_COLOR: always
+    DOCS_NAME: ${{ inputs.name || github.ref.name }}
+    PUBLIC_DOCS_DIR: /Users/rohan/Downloads/substrate_docs_public
+
+jobs:
+  deploy-docs:
+    name: Deploy documentation
+    runs-on: bwrc
+    environment: docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'yarn'
+          cache-dependency-path: docs/docusaurus/yarn.lock
+      - run: ./deploy.sh ${{ env.PUBLIC_DOCS_DIR }} ${{ inputs.name || github.ref_name }}
+        working-directory: docs/docusaurus
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_DOCS }}
+

.github/workflows/deploy-release-api-docs.yml

@@ -0,0 +1,11 @@
+name: deploy-release-api-docs
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy-api-docs:
+    uses: ./.github/workflows/deploy-api-docs.yml
+    with:
+      name: release

.release-please-manifest.json

@@ -3,7 +3,9 @@
   "codegen": "0.8.1",
   "config": "0.2.5",
   "docs/snippets": "0.5.1",
-  "libs/atoll": "0.1.3",
+  "examples/latest/sky130_inverter": "0.0.0",
+  "examples/latest/spice_vdivider": "0.0.0",
+  "examples/latest/substrate_api_examples": "0.0.0",
   "libs/cache": "0.5.0",
   "libs/diagnostics": "0.3.0",
   "libs/enumify": "0.1.0",

Cargo.toml

@@ -7,7 +7,10 @@ members = [
     "codegen",
     "config",
     "docs/snippets",
-    # "libs/atoll",
+    # "examples/latest/sky130_inverter",
+    # "examples/latest/spice_vdivider",
+    "examples/latest/colbuf",
+    # "examples/latest/substrate_api_examples",
     "libs/cache",
     "libs/diagnostics",
     "libs/layir",
@@ -29,16 +32,15 @@ members = [
     "libs/verilog",
     # "pdks/sky130pdk",
     "substrate",
-    # "tests",
+    "tests",
     "tools/magic",
     "tools/netgen",
     "tools/ngspice",
     "tools/pegasus",
     "tools/quantus",
     "tools/spectre", 
     "tools/magic-netgen",
-    "examples2/colbuf", "examples2/via",
 ]
 
-exclude = ["tests", "pdks/sky130pdk", "libs/atoll", "examples"]
+exclude = ["pdks/sky130pdk", "examples/release"]
 

codegen/build.rs

@@ -1,12 +1,10 @@
 use snippets::build_snippets;
 
 fn main() {
-    println!("cargo::rerun-if-changed=examples/example.rs");
-    build_snippets(
-        concat!(
-            env!("CARGO_MANIFEST_DIR"),
-            "/../substrate/examples/substrate.rs"
-        ),
-        "substrate",
+    let example_path = concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../examples/latest/substrate_api_examples/src/lib.rs"
     );
+    println!("cargo::rerun-if-changed={example_path}");
+    build_snippets(example_path, "substrate");
 }

docs/api/deploy.sh

@@ -0,0 +1,22 @@
+# Print commands that are executed
+set -x
+
+# Turn on error checking options
+# Running the bashrc can result in errors,
+# which we'll just ignore.
+set -euf -o pipefail
+
+if [ $# -le 1 ]; then
+    echo "Usage: ./deploy.sh PUBLIC_DOCS_DIR REF_NAME"
+    exit 1
+fi
+
+PUBLIC_DOCS_DIR=$1
+REF_NAME=$2
+
+just build
+rm -rf $PUBLIC_DOCS_DIR/api/static/$REF_NAME
+mkdir -p $PUBLIC_DOCS_DIR/api/static/$REF_NAME
+cp -r ./target/doc/. $PUBLIC_DOCS_DIR/api/static/$REF_NAME
+cd $PUBLIC_DOCS_DIR/api
+flyctl deploy --remote-only --detach

docs/docusaurus/blog/24-12-24-example-post/index.md

@@ -0,0 +1,10 @@
+---
+authors:
+  - rohanku
+slug: /example-post
+description: Test description
+---
+
+# Example post
+
+Test

docs/docusaurus/create_version.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+(cd $SCRIPT_DIR \
+    && yarn docusaurus docs:version $1 \
+    && echo "{\"examples_path\": \"examples/$1\"}" > "versioned_docs/version-$1/docs-config.json")

docs/docusaurus/deploy.sh

@@ -0,0 +1,35 @@
+# Print commands that are executed
+set -x
+
+# Turn on error checking options
+# Running the bashrc can result in errors,
+# which we'll just ignore.
+set -euf -o pipefail
+
+if [ $# -eq 0 ]
+  then
+    echo "Usage: ./deploy.sh PUBLIC_DOCS_DIR REF_NAME"
+    exit 1
+fi
+
+PUBLIC_DOCS_DIR=$1
+REF_NAME=$2
+
+cat << EOF > ./site-config.json
+{
+    "branch": "$REF_NAME"
+}
+EOF
+yarn install
+yarn build
+if [ $REF_NAME = "main" ]; then
+    find $PUBLIC_DOCS_DIR/docusaurus/static -not -path "$PUBLIC_DOCS_DIR/docusaurus/static/branch/*" -not -name "fly.toml" -not -name "Dockerfile" -delete
+    mkdir -p $PUBLIC_DOCS_DIR/docusaurus/static
+    cp -r ./build/. $PUBLIC_DOCS_DIR/docusaurus/static
+else
+    rm -rf $PUBLIC_DOCS_DIR/docusaurus/static/branch/$REF_NAME
+    mkdir -p $PUBLIC_DOCS_DIR/docusaurus/static/branch/$REF_NAME
+    cp -r ./build/. $PUBLIC_DOCS_DIR/docusaurus/static/branch/$REF_NAME
+fi
+cd $PUBLIC_DOCS_DIR/docusaurus
+flyctl deploy --remote-only --detach