From f5f626ce6bcb61f00fd3e76b12f84122d1f300ec Mon Sep 17 00:00:00 2001 From: MSalopek Date: Tue, 30 Apr 2024 13:13:24 +0200 Subject: [PATCH] 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 <98309852+mmulji-ic@users.noreply.github.com> --- .github/workflows/deploy-docs.yml | 4 ++- .gitignore | 4 +++ Makefile | 7 ++-- docs/README.md | 54 ++++++++++++++++++++++++------- docs/build.sh | 10 ------ docs/build_deploy.sh | 10 ++++++ docs/build_local.sh | 5 +++ docs/docusaurus.config.js | 26 +++++++++++++-- docs/sync_versions.sh | 30 +++++++++++++++++ docs/versions.json | 5 +++ 10 files changed, 127 insertions(+), 28 deletions(-) delete mode 100755 docs/build.sh create mode 100755 docs/build_deploy.sh create mode 100755 docs/build_local.sh create mode 100755 docs/sync_versions.sh create mode 100644 docs/versions.json diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 8e36cd6cda..f95a6c2b0e 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -37,7 +37,9 @@ jobs: - name: Build 🔧 run: | npm install -g npm@10.2.4 - make build-docs + cd docs + ./sync_versions.sh + ./build_deploy.sh - name: Deploy 🚀 uses: JamesIves/github-pages-deploy-action@v4.5.0 diff --git a/.gitignore b/.gitignore index e83a69a504..96e3251977 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,7 @@ vendor/ build/ .vscode .idea + +# docusaurus versioned docs created during build +docs/versioned_docs +docs/versioned_sidebars diff --git a/Makefile b/Makefile index 26f2fe7f1d..15fd06355d 100644 --- a/Makefile +++ b/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 ### diff --git a/docs/README.md b/docs/README.md index aaba2fa1e1..d7be3a22ab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,17 @@ # 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. @@ -19,23 +19,55 @@ This command starts a local development server and opens up a browser window. Mo ### 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= 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 ) + +## 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. diff --git a/docs/build.sh b/docs/build.sh deleted file mode 100755 index b39a0539a6..0000000000 --- a/docs/build.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/sh - -# This builds docs using docusaurus. -COMMIT=$(git rev-parse HEAD) -echo "building docusaurus main docs" -(git clean -fdx && git reset --hard && git checkout $COMMIT) -npm ci && npm run build -mv build ~/output -echo "done building docusaurus main docs" -# echo $DOCS_DOMAIN > ~/output/CNAME diff --git a/docs/build_deploy.sh b/docs/build_deploy.sh new file mode 100755 index 0000000000..9cc8fcf161 --- /dev/null +++ b/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" diff --git a/docs/build_local.sh b/docs/build_local.sh new file mode 100755 index 0000000000..b93f147b0a --- /dev/null +++ b/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" diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index e9c2b1e75c..5c85a14825 100644 --- a/docs/docusaurus.config.js +++ b/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: "/", }, ], diff --git a/docs/sync_versions.sh b/docs/sync_versions.sh new file mode 100755 index 0000000000..2aae4335d8 --- /dev/null +++ b/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 + + diff --git a/docs/versions.json b/docs/versions.json new file mode 100644 index 0000000000..e0778f2e0e --- /dev/null +++ b/docs/versions.json @@ -0,0 +1,5 @@ +[ + "v4.0.0", + "v4.1.0", + "v5.0.0-rc0" +] \ No newline at end of file