From cb085cb76737e4af568002f1083352b96839936b Mon Sep 17 00:00:00 2001 From: Etai Lev Ran Date: Tue, 30 Apr 2024 10:32:47 +0300 Subject: [PATCH] Automation script to generate new docs version (#540) * Automate doc versioning * move params.versions to end of file * document manual steps in TODO --------- Signed-off-by: Etai Lev Ran --- Makefile | 8 ++++ hack/gen-doc-version.sh | 92 +++++++++++++++++++++++++++++++++++++++++ website/config.toml | 19 +++++---- 3 files changed, 110 insertions(+), 9 deletions(-) create mode 100755 hack/gen-doc-version.sh diff --git a/Makefile b/Makefile index 9f0c1592..8af44d47 100755 --- a/Makefile +++ b/Makefile @@ -69,6 +69,14 @@ vet-go: ; $(info vetting code...) copr-fix: ; $(info adding copyright header...) docker run -it --rm -v $(shell pwd):/github/workspace apache/skywalking-eyes header fix +#------------------------------------------------------ +# docs targets +# Note: most are in website/Makefile +#------------------------------------------------------ +.PHONY: docs-version +docs-version: + ./hack/gen-doc-version.sh + #------------------------------------------------------ # Build targets #------------------------------------------------------ diff --git a/hack/gen-doc-version.sh b/hack/gen-doc-version.sh new file mode 100755 index 00000000..dd43f024 --- /dev/null +++ b/hack/gen-doc-version.sh @@ -0,0 +1,92 @@ +#!/bin/bash + +# Copyright 2024 The ClusterLink Authors. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +# gen-doc-version is used by the "make docs-version" target in Makefile. +# It generates a new versioned documentation directory under website/content/en/docs +# using the following process: +# 1. Create a new directory for `$NEW_DOCS_VERSION` +# 2. Copy and git commit the contents of the last released docs directory +# (`$PREVIOUS_DOCS_VERSION``) into the new directory, to establish a baseline +# for documentation comparison. +# 3. Delete and replaces the contents of the new docs directory with the +# contents of the 'main' docs directory. +# 4. Update and version and/or revision specific value in the documentation. +# +# The unstaged changes in the working directory can now easily be diff'ed +# using 'git diff' to review all docs changes made since the previous +# released version. Once the unstaged changes are ready, they can be added +# and committed. +# +# To run gen-doc-version: "NEW_DOCS_VERSION=v0.2.0 PREVIOUS_DOCS_VERSION=v0.1.0 make docs-version" +# Note: if PREVIOUS_DOCS_VERSION is not set, the script will guess it from the directory listing +# + +set -o errexit +set -o nounset +set -o pipefail + +DOCS_DIRECTORY=website/content/en/docs +CONFIG_FILE=website/config.toml +MAIN_BRANCH=main +INDEX_MD=_index.md + +# NEW_DOCS_VERSION must be defined +if [[ -z "${NEW_DOCS_VERSION:-}" ]]; then + echo "ERROR: \$NEW_DOCS_VERSION environment variable must be defined" + exit 1 +fi + +# don't run if there's already a directory for the target docs version +if [[ -d $DOCS_DIRECTORY/$NEW_DOCS_VERSION ]]; then + echo "ERROR: $DOCS_DIRECTORY/$NEW_DOCS_VERSION already exists" + exit 1 +fi + +# get the alphabetically last item in $DOCS_DIRECTORY to use as PREVIOUS_DOCS_VERSION +# if not explicitly specified by the user +if [[ -z "${PREVIOUS_DOCS_VERSION:-}" ]]; then + echo "PREVIOUS_DOCS_VERSION was not specified, getting the latest version" + PREVIOUS_DOCS_VERSION=$(ls -1 $DOCS_DIRECTORY/ | tail -n 1) +fi + +# make a copy of the previous versioned docs dir +git checkout -b ${NEW_DOCS_VERSION} +echo "Creating copy of docs directory $DOCS_DIRECTORY/$PREVIOUS_DOCS_VERSION in $DOCS_DIRECTORY/$NEW_DOCS_VERSION" +cp -r $DOCS_DIRECTORY/${PREVIOUS_DOCS_VERSION}/ $DOCS_DIRECTORY/${NEW_DOCS_VERSION}/ + +# Copy the previous version's docs as-is so we get a useful diff when we copy the $MAIN_BRANCH docs in +echo "Running 'git add' for previous version's doc contents to use as a base for diff" +git add -f $DOCS_DIRECTORY/${NEW_DOCS_VERSION} + +# Delete all and then copy the contents of $DOCS_DIRECTORY/$MAIN_BRANCH into +# the same directory so we can get git diff of what changed since previous version +echo "Copying $DOCS_DIRECTORY/$MAIN_BRANCH/ to $DOCS_DIRECTORY/${NEW_DOCS_VERSION}/" +rm -rf $DOCS_DIRECTORY/${NEW_DOCS_VERSION}/ && cp -r $DOCS_DIRECTORY/$MAIN_BRANCH/ $DOCS_DIRECTORY/${NEW_DOCS_VERSION}/ + +# replace known version-specific links +echo "Updating config file" +sed -i'' "s/latest_stable_version = ${PREVIOUS_DOCS_VERSION}/latest_stable_version = ${NEW_DOCS_VERSION}/" $CONFIG_FILE + +# TODO: automate some of the below +echo "Done - $DOCS_DIRECTORY/$NEW_DOCS_VERSION has been created" +echo "" +echo "1. Run a 'git status' / 'git diff' to review all changes made to the docs since the previous version." +echo "2. Make any manual changes/corrections necessary. For example:" +echo " - Remove docs directories of deprecated/EOL versions, if any." +echo " - Revert latest_stable_version in $CONFIG_FILE for non-GA releases." +echo " - Add version ${NEW_DOCS_VERSION} to [params.versions] list in ${CONFIG_FILE} (after main, above ${PREVIOUS_DOCS_VERSION})." +echo " - Fix frontmatter in $DOCS_DIRECTORY/${NEW_DOCS_VERSION}/${INDEX_MD}." +echo "3. Run 'git add' to stage all unstaged changes, then 'git commit'." diff --git a/website/config.toml b/website/config.toml index 694e26cf..c1c060fb 100644 --- a/website/config.toml +++ b/website/config.toml @@ -202,15 +202,6 @@ weight = 10 url = "/docs/v0.1.0" pre = "" -# Add your release versions here -[[params.versions]] -version = "main-DRAFT" -url = "/docs/main" - -[[params.versions]] -version = "v0.1.0" -url = "/docs/v0.1.0/" - # hugo module configuration [module] [module.hugoVersion] @@ -222,3 +213,13 @@ path = "github.com/google/docsy" path = "github.com/google/docsy/dependencies" [[module.imports]] path = "github.com/martignoni/hugo-notice" + +# Add your release versions here. +# NOTE: Please keep this section last as ./hack/gen-doc-version.sh depends on it +[[params.versions]] +version = "main-DRAFT" +url = "/docs/main" + +[[params.versions]] +version = "v0.1.0" +url = "/docs/v0.1.0/"