From bd5c24a435bbbbcedb77de1a1b52e1bbb88c7d86 Mon Sep 17 00:00:00 2001 From: Joakim Ahrlin Date: Wed, 26 Jan 2022 13:00:40 +0100 Subject: [PATCH 1/2] break out CLI generation into separate function generate current docs at the correct place generate next docs with CLI Signed-off-by: Joakim Ahrlin --- scripts/gendocs/generate | 45 +++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/scripts/gendocs/generate b/scripts/gendocs/generate index 5a25b6c5ba2..430caa4c7ed 100755 --- a/scripts/gendocs/generate +++ b/scripts/gendocs/generate @@ -63,18 +63,20 @@ gencliversions="${1:-0}" genversion() { checkout "$1" gendocs "$2" +} + +genversionwithcli() { + genversion "$1" "$2" - if [ "$gencliversions" == 1 ]; then - genclireference "$2" "cmd/acmesolver" "acmesolver" - genclireference "$2" "cmd/cainjector" "cainjector" - genclireference "$2" "cmd/ctl" "cmctl" - genclireference "$2" "cmd/controller" "controller" - genclireference "$2" "cmd/webhook" "webhook" - - # if any of the above steps succeeded copy over the index file - if [ -d "$REPO_ROOT/content/en/$2/cli" ]; then - cp "$REPO_ROOT/content/en/docs/cli/_index.md" "${REPO_ROOT}/content/en/$2/cli/" - fi + genclireference "$2" "cmd/acmesolver" "acmesolver" + genclireference "$2" "cmd/cainjector" "cainjector" + genclireference "$2" "cmd/ctl" "cmctl" + genclireference "$2" "cmd/controller" "controller" + genclireference "$2" "cmd/webhook" "webhook" + + # if any of the above steps succeeded copy over the index file + if [ -d "$REPO_ROOT/content/en/$2/cli" ]; then + cp "$REPO_ROOT/content/en/docs/cli/_index.md" "${REPO_ROOT}/content/en/$2/cli/" fi } @@ -142,21 +144,22 @@ $output EOF } -genclireference "docs" "cmd/acmesolver" "acmesolver" -genclireference "docs" "cmd/cainjector" "cainjector" -genclireference "docs" "cmd/ctl" "cmctl" -genclireference "docs" "cmd/controller" "controller" -genclireference "docs" "cmd/webhook" "webhook" - # The branches named here exist in the `jetstack/cert-manager` repo. -genversion "release-1.7" "next-docs" +genversionwithcli "release-1.7" "next-docs" # In cert-manager 1.6 cert-manager.io and acme.cert-manager.io alpha and beta # API versions are no longer served, but the apis are still in the codebase. We # don't want to show the docs for those API versions so this is a workaround. # This will only be necessary for the release-1.6 branch. checkout "release-1.6" + +genclireference "docs" "cmd/acmesolver" "acmesolver" +genclireference "docs" "cmd/cainjector" "cainjector" +genclireference "docs" "cmd/ctl" "cmctl" +genclireference "docs" "cmd/controller" "controller" +genclireference "docs" "cmd/webhook" "webhook" + rm -r pkg/apis/acme/v1alpha2 rm -r pkg/apis/acme/v1alpha3 rm -r pkg/apis/acme/v1beta1 @@ -174,9 +177,9 @@ rm -r pkg/apis/certmanager/v1alpha3 rm -r pkg/apis/certmanager/v1beta1 gendocs "v1.6-docs" -# when adding a new version here run -# ./scripts/gendocs/generate 1 to force generation of CLI docs -# and add them to the git index +# when adding a new version here use +# genversionwithcli to force generation of CLI docs +# and add them to the git index, then switch back to genversion genversion "release-1.5" "v1.5-docs" genversion "release-1.4" "v1.4-docs" genversion "release-1.3" "v1.3-docs" From 1c28402e7483d7c70df1d213b56faec40dd08463 Mon Sep 17 00:00:00 2001 From: Joakim Ahrlin Date: Wed, 26 Jan 2022 16:36:53 +0100 Subject: [PATCH 2/2] improve generate script documentation comments Signed-off-by: Joakim Ahrlin --- scripts/gendocs/generate | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/scripts/gendocs/generate b/scripts/gendocs/generate index 430caa4c7ed..4ead5bd9620 100755 --- a/scripts/gendocs/generate +++ b/scripts/gendocs/generate @@ -148,18 +148,23 @@ EOF genversionwithcli "release-1.7" "next-docs" -# In cert-manager 1.6 cert-manager.io and acme.cert-manager.io alpha and beta -# API versions are no longer served, but the apis are still in the codebase. We -# don't want to show the docs for those API versions so this is a workaround. -# This will only be necessary for the release-1.6 branch. checkout "release-1.6" +# At the top of this script we pull the repository from the latest from master. +# These commands must follow an explicit checkout of the latest release, +# otherwise unreleased CLI flags are included. +# For 1.6 they must happen before removing the legacy APIs +# as it will not compile without them. genclireference "docs" "cmd/acmesolver" "acmesolver" genclireference "docs" "cmd/cainjector" "cainjector" genclireference "docs" "cmd/ctl" "cmctl" genclireference "docs" "cmd/controller" "controller" genclireference "docs" "cmd/webhook" "webhook" +# In cert-manager 1.6 cert-manager.io and acme.cert-manager.io alpha and beta +# API versions are no longer served, but the apis are still in the codebase. We +# don't want to show the docs for those API versions so this is a workaround. +# This will only be necessary for the release-1.6 branch. rm -r pkg/apis/acme/v1alpha2 rm -r pkg/apis/acme/v1alpha3 rm -r pkg/apis/acme/v1beta1 @@ -177,9 +182,10 @@ rm -r pkg/apis/certmanager/v1alpha3 rm -r pkg/apis/certmanager/v1beta1 gendocs "v1.6-docs" +# from 1.7 and onward: # when adding a new version here use -# genversionwithcli to force generation of CLI docs -# and add them to the git index, then switch back to genversion +# genversionwithcli, for example: +# genversionwithcli "release-1.6" "v1.6-docs" genversion "release-1.5" "v1.5-docs" genversion "release-1.4" "v1.4-docs" genversion "release-1.3" "v1.3-docs"