docs: update versions; update process docs (#2080)

* docs: rm version.json; read version from supported_versions; bump process

* update documentation README

* Update docs/README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update docs/README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update docs/README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update docs/README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

.gitignore

@@ -10,5 +10,6 @@ build/
 .idea
 
 # docusaurus versioned docs created during build
+docs/versions.json
 docs/versioned_docs
 docs/versioned_sidebars

RELEASE_PROCESS.md

@@ -109,18 +109,9 @@ Once the **final release** is cut, the new changelog section must be added to ma
 
 ## Updating published docs
 
-### Before tagging a new release
-
-On your release branch, clear the `docs/versions.json` file so it looks like this:
-```json
-[]
-```
-
-If this file is populated on a release branch it will cause the tag to have extra files that the docs deploy process does not expect. This could cause the deploy process to fail in some situations.
-
 ### After tagging a new release
 
-Go to `main` branch and update the `docs/versions.json` to include all the versions you want to publish on the docs page:
+Go to `main` branch and update the `docs/supported_versions.json` to include all the versions you want to publish on the docs page:
 ```json
 [
     "v4.3.0",
@@ -130,51 +121,6 @@ Go to `main` branch and update the `docs/versions.json` to include all the versi
 
 This will cause the docs to be built with `main`, `v4.3.0` and `v5.0.0`.
 
-In `docs/docusaurus.config.js` change the `preset` section to display the versions you chose in `docs/versions.json`.
-
-For example, here we remove v4.2.0 and replace it with v4.3.0.
-
-```diff
-  presets: [
-    [
-      "classic",
-      /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
-        docs: {
-          sidebarPath: require.resolve("./sidebars.js"),
-          routeBasePath: "/",
-          versions: {
-            current: {
-              path: "/",
-              label: "main",
-              banner: "unreleased",
-            },
-            // v4.2.0-docs was a special tags for docs
-            // this is not usually necessary
--            "v4.2.0-docs": {
--              path: "/v4.2.0/",
--              label: "v4.2.0",
--              banner: "none",
--            },
-+            "v4.3.0": {
-+              banner: "none",
-+            },
-            "v5.0.0": {
-              banner: "unreleased",
-            },
-          },
-          remarkPlugins: [remarkMath],
-          rehypePlugins: [rehypeKatex],
-        },
-
-        theme: {
-          customCss: require.resolve("./src/css/custom.css"),
-        },
-      }),
-    ],
-  ],
-```
-
 The documentation is updated automatically whenever `main` is changed.
 
 To learn how to work with docs locally check the docs [README.md on main branch](https://github.com/cosmos/interchain-security/blob/main/docs/README.md)

docs/README.md

@@ -24,6 +24,7 @@ $ npm run build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+This is not intended for local development but it is used during the deploy sequence.
 
 # Adding versions
 
@@ -53,9 +54,12 @@ The script above will create `versioned_docs` and `versioned_sidebars` directori
 To view the docs run:
 
 ```shell
+cp supported_versions.json versions.json # needed to show the version dropdown
 npm run start
 ```
 
+Remove `versions.json` after use to prevent interference with local documentation.
+
 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>)
 
@@ -71,3 +75,23 @@ The script switches branches while building the versioned docs - **please note t
 The `./docs/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 `./docs/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.
+
+
+# Scripts and make commands
+
+`build_deploy.sh` script builds the documentation output directory for serving static HTML files. It should be executed on the remote server.
+
+`build_local.sh` will build the documentation locally by running `npm run build`. You can check the built web page by running `npm run serve` after the build command completes.
+
+`sync_versions.sh` will fetch and build all docs versions specified in `supported_versions.json`. It is intended to be executed on the remote server.
+
+`versions.json` must remain empty or be removed from your worktree. Avoid pushing it to GitHub.
+* this file specifies which versions will be displayed in the supported versions drop down on the docs page
+* instead of using it, the supported versions should live in `supported_versions.json`
+* this file should only be populated during deployment and never on your local machine
+
+# Building on remote
+
+Building on remote host is handled by [deploy-docs.yml workflow](.github/workflows/deploy-docs.yml).
+
+It executes `./sync_versions.sh` and `./build_deploy.sh` scripts and allows the output of the build proces to be served by github pages.

docs/build_deploy.sh

@@ -2,6 +2,7 @@
 
 # build versioned docs prepared by sync_versions.sh
 echo "building docusaurus main docs"
+cp supported_versions.json versions.json
 npm ci && npm run build
 
 # copy "legacy" docs directory into the final build directory

docs/docusaurus.config.js

@@ -39,21 +39,6 @@ const config = {
         docs: {
           sidebarPath: require.resolve("./sidebars.js"),
           routeBasePath: "/",
-          versions: {
-            current: {
-              path: "/",
-              label: "main",
-              banner: "unreleased",
-            },
-            "v4.2.0-docs": {
-              path: "/v4.2.0/",
-              label: "v4.2.0",
-              banner: "none",
-            },
-            "v5.0.0": {
-              banner: "unreleased",
-            },
-          },
           remarkPlugins: [remarkMath],
           rehypePlugins: [rehypeKatex],
           exclude: ["**/templates/*"],

docs/supported_versions.json

@@ -0,0 +1,4 @@
+[
+    "v5.1.0",
+    "v4.4.1"
+]

docs/sync_versions.sh

@@ -7,7 +7,7 @@
 if git diff-index --quiet HEAD --; then
     # initial branch
     COMMIT=$(git rev-parse HEAD)
-    for version in $(jq -r .[] versions.json); do
+    for version in $(jq -r .[] supported_versions.json); do
         echo "Building docusaurus $version docs ..."
         git checkout $version
         npm cache clean --force && npm install && npm run docusaurus docs:version $version