docs: add docs versioning and legacy page (pre v4.0.0) (#1833)

* Updated build to allow for versioned docs

* wip: add steps to build legacy docs

* docs: add build legacy website

* docs: add v4; rename to legacy

* docs: add docs versioning for docusaurus v3.x

* docs: add docs version sync and deploy scripts

* update makefile

* docs: rm deprecated build script

* docs: fix banner in v4.1.0

* docs: update build script & config

* update .gitignore

* docs: update build script & config

* docs: update Readme

* build: update docs build script

* build: update docs README.md

* address review comments

* address review comments -- update readme

---------

Co-authored-by: Milan Mulji <[email protected]>

.github/workflows/deploy-docs.yml

@@ -37,7 +37,9 @@ jobs:
       - name: Build 🔧
         run: |
           npm install -g [email protected]
-          make build-docs
+          cd docs
+          ./sync_versions.sh
+          ./build_deploy.sh
 
       - name: Deploy 🚀
         uses: JamesIves/[email protected]

.gitignore

@@ -8,3 +8,7 @@ vendor/
 build/
 .vscode
 .idea
+
+# docusaurus versioned docs created during build
+docs/versioned_docs
+docs/versioned_sidebars

Makefile

@@ -246,10 +246,11 @@ proto-update-deps:
 ###                              Documentation                              ###
 ###############################################################################
 
-build-docs:
-	@cd docs && ./build.sh
+build-docs-deploy:
+	@cd docs && ./sync_versions.sh && ./build_deploy.sh
 
-.PHONY: build-docs
+build-docs-local:
+	@cd docs && ./build_local.sh
 
 ###############################################################################
 ### 							Test Traces									###

docs/README.md

@@ -1,41 +1,73 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
 ```
-$ yarn
+$ npm install
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+$ npm run start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
 ```
-$ yarn build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
 
-Using SSH:
+# Adding versions
 
+To add/remove versions from the page you can modify `versions.json`.
+
+At the time of writing it looked like this:
+```json
+[
+    "v4.0.0",
+    "v4.1.0",
+    "v5.0.0-rc0"
+]
 ```
-$ USE_SSH=true yarn deploy
-```
 
-Not using SSH:
+You can remove any version that you no longer need and the build process will remove it from the final page.
+
+
+# Accessing versioned docs locally
 
+```shell
+# from interchain-security/docs run:
+./sync_versions.sh
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+
+The script above will create `versioned_docs` and `versioned_sidebars` directories inside `interchain-security/docs`.
+
+To view the docs run:
+
+```shell
+npm run start
 ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+Remember to check back out to your working branch. Running `./sync_versions.sh` will leave you in a detached head state.
+(simply run `git checkout <working-branch>)
+
+## Note:
+The script will exit if you have uncommitted changes.
+The script switches branches while building the versioned docs - **please note that this could overwrite your local changes**.
+
+
+# Legacy documentation
+
+`legacy-docs-page` [branch](https://github.com/cosmos/interchain-security/tree/legacy-docs-page) contains documentation for versions `<= v4.0.0`. These versions were built using docusaurus `v2.4.0` which is not compatible with docusaurus `v3.x` used at the time of writing. It was not feasible to port the legacy docs from `v2.4.0` because `v3.x` is not compatible with it and it required changing all release branches.
+
+The `legacy` directory on `legacy-docs-page` was created manually, by modifying `docusaurus.config.js` and `versions.json` on `https://github.com/cosmos/interchain-security/releases/v3.3.1-lsm` and generating the static pages manually using `npm run build`.
+
+The `legacy` directory gets included into the rest of the documentation using a simple `cp` command during the deploy process using the [build_deploy.sh](./build_deploy.sh) script. It is **not** included during local builds.

docs/build_deploy.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+echo "building docusaurus main docs"
+npm ci && npm run build
+# copy legacy docs to build folder
+git fetch origin legacy-docs-page
+git checkout origin/legacy-docs-page -- legacy
+cp -r ./legacy ./build/
+mv build ~/output
+echo "done building docusaurus main docs"

docs/build_local.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+echo "building docusaurus from local branch"
+npm ci && npm run build
+echo "done building docusaurus from local docs"

docs/docusaurus.config.js

@@ -39,10 +39,23 @@ const config = {
         docs: {
           sidebarPath: require.resolve("./sidebars.js"),
           routeBasePath: "/",
+          lastVersion: "v4.1.0",
           versions: {
             current: {
               path: "/",
-              // banner: "current",
+              label: "main",
+              banner: "unreleased",
+            },
+            "v4.0.0": {
+              path: "/v4.0.0/",
+              banner: "none",
+            },
+            "v4.1.0": {
+              path: "/v4.1.0/",
+              banner: "none",
+            },
+            "v5.0.0-rc0": {
+              banner: "unreleased",
             },
           },
           remarkPlugins: [remarkMath],
@@ -91,7 +104,14 @@ const config = {
           {
             type: "docsVersionDropdown",
             position: "left",
-            dropdownActiveClassDisabled: true,
+            dropdownActiveClassDisabled: false,
+            dropdownItemsAfter: [
+              {
+                href: "https://cosmos.github.io/interchain-security/legacy",
+                label: "<= v3.x",
+                target: "_blank",
+              },
+            ],
           },
         ],
       },
@@ -211,7 +231,7 @@ const config = {
         toExtensions: ["html"],
         redirects: [
           {
-            from: ["/main", "/master"],
+            from: ["/main"],
             to: "/",
           },
         ],

docs/sync_versions.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+
+# this script builds the docs for all versions in versions.json
+# all the versions are included in the docs webpage
+
+# exit if there are uncommited changes
+if git diff-index --quiet HEAD --; then
+    # initial branch
+    COMMIT=$(git rev-parse HEAD)
+    for version in $(jq -r .[] versions.json); do
+        echo "Building docusaurus $version docs ..."
+        git checkout $version
+        npm cache clean --force && npm install && npm run docusaurus docs:version $version
+
+        # versions.json / package-lock.json, get mangled by Docusarus causing problems
+        rm versions.json package-lock.json
+    done
+
+    # return to initial branch but keep the files created by Docusarus in the loop above
+    (git reset --hard && git checkout $COMMIT)
+
+    # copy figures so they are available to all versioned docs
+    cp -R figures ./versioned_docs/
+else
+
+    echo "Please commit all changes before running this script"
+    exit 1
+fi
+
+

docs/versions.json

@@ -0,0 +1,5 @@
+[
+    "v4.0.0",
+    "v4.1.0",
+    "v5.0.0-rc0"
+]