From 9cd63479688a439f28487a96dc0307ec3ac6ab06 Mon Sep 17 00:00:00 2001 From: Steve Kriss Date: Thu, 30 Apr 2020 16:12:11 -0600 Subject: [PATCH] change scripts/docs to generate one docs site per major.minor (#2473) Signed-off-by: Steve Kriss --- Makefile | 2 +- hack/gen-docs.sh | 8 ++++---- site/README-JEKYLL.md | 6 ++++-- site/_includes/version-warning.html | 2 +- site/docs/master/release-instructions.md | 7 +++++-- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/Makefile b/Makefile index 66a5a6d10..706fd7171 100644 --- a/Makefile +++ b/Makefile @@ -290,7 +290,7 @@ serve-docs: # tagged version. Once the unstaged changes are ready, they can be added to the # staging area using 'git add' and then committed. # -# To run gen-docs: "NEW_DOCS_VERSION=v1.1.0 make gen-docs" +# To run gen-docs: "NEW_DOCS_VERSION=v1.4 VELERO_VERSION=v1.4.0 make gen-docs" # # **NOTE**: there are additional manual steps required to finalize the process of generating # a new versioned docs site. The full process is documented in site/README-JEKYLL.md. diff --git a/hack/gen-docs.sh b/hack/gen-docs.sh index 041d8513a..dccb13725 100755 --- a/hack/gen-docs.sh +++ b/hack/gen-docs.sh @@ -66,8 +66,8 @@ rm site/_data/$NEW_DOCS_TOC.yml && cp site/_data/master-toc.yml site/_data/$NEW_ # so check which OS we're running on. if [[ $(uname) == "Darwin" ]]; then echo "[OS X] updating version-specific links" - find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i '' "s|https://velero.io/docs/master|https://velero.io/docs/$NEW_DOCS_VERSION|g" - find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i '' "s|https://github.com/vmware-tanzu/velero/blob/master|https://github.com/vmware-tanzu/velero/blob/$NEW_DOCS_VERSION|g" + find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i '' "s|https://velero.io/docs/master|https://velero.io/docs/$VELERO_VERSION|g" + find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i '' "s|https://github.com/vmware-tanzu/velero/blob/master|https://github.com/vmware-tanzu/velero/blob/$VELERO_VERSION|g" echo "[OS X] Updating latest version in _config.yml" sed -i '' "s/latest: ${PREVIOUS_DOCS_VERSION}/latest: ${NEW_DOCS_VERSION}/" site/_config.yml @@ -86,8 +86,8 @@ ${NEW_DOCS_VERSION}: ${NEW_DOCS_TOC} else echo "[Linux] updating version-specific links" - find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i'' "s|https://velero.io/docs/master|https://velero.io/docs/$NEW_DOCS_VERSION|g" - find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i'' "s|https://github.com/vmware-tanzu/velero/blob/master|https://github.com/vmware-tanzu/velero/blob/$NEW_DOCS_VERSION|g" + find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i'' "s|https://velero.io/docs/master|https://velero.io/docs/$VELERO_VERSION|g" + find site/docs/${NEW_DOCS_VERSION} -type f -name "*.md" | xargs sed -i'' "s|https://github.com/vmware-tanzu/velero/blob/master|https://github.com/vmware-tanzu/velero/blob/$VELERO_VERSION|g" echo "[Linux] Updating latest version in _config.yml" sed -i'' "s/latest: ${PREVIOUS_DOCS_VERSION}/latest: ${NEW_DOCS_VERSION}/" site/_config.yml diff --git a/site/README-JEKYLL.md b/site/README-JEKYLL.md index 59f25ab75..c86827f5c 100644 --- a/site/README-JEKYLL.md +++ b/site/README-JEKYLL.md @@ -40,8 +40,10 @@ To add a new set of versioned docs to go with a new Velero release: 1. In the root of the repository, run: ```bash - # set to the appropriate version number - NEW_DOCS_VERSION=vX.Y.Z make gen-docs + # set to the appropriate version numbers + NEW_DOCS_VERSION=vX.Y VELERO_VERSION=vX.Y.Z make gen-docs ``` 1. In `site/_config.yml`, under the `defaults` field, add an entry for the new version just under `master` by copying the most recent version's entry and updating the version numbers. + +1. [Pre-release only] In `site/_config.yml`, revert the change to the `latest` field, so the pre-release docs do not become the default. diff --git a/site/_includes/version-warning.html b/site/_includes/version-warning.html index 63e9f5e88..5a94a4f32 100644 --- a/site/_includes/version-warning.html +++ b/site/_includes/version-warning.html @@ -7,7 +7,7 @@ unstable, and these docs are not guaranteed to be up to date or correct. See the latest version.

-{% elsif page.version contains 'beta' or page.version contains 'alpha' or page.version contains 'rc' %} +{% elsif page.version contains 'beta' or page.version contains 'alpha' or page.version contains 'rc' or page.version contains 'pre' %}

This is the documentation for the latest pre-production version of Velero. Both code and docs may be diff --git a/site/docs/master/release-instructions.md b/site/docs/master/release-instructions.md index c249a62ee..b77f6ac18 100644 --- a/site/docs/master/release-instructions.md +++ b/site/docs/master/release-instructions.md @@ -17,12 +17,15 @@ You also need to update `site/index.html` to have "Latest Release Information" c 1. Update the main `CHANGELOG.md` file to properly reference the release-specific changelog file: - (Pre-Release) List the release under "Development release" - (GA) List the release under "Current release", remove any pre-releases from "Development release", and move the previous release into "Older releases". -1. If there is an existing set of pre-release versioned docs for the version you are releasing (i.e. `site/docs/v1.2.0-beta.1` exists, and you're releasing `v1.2.0-beta.2` or `v1.2.0`): +1. If there is an existing set of pre-release versioned docs for the version you are releasing (i.e. `site/docs/v1.4-pre` exists, and you're releasing `v1.4.0-beta.2` or `v1.4.0`): - Remove the directory containing the pre-release docs, i.e. `site/docs/`. - Delete the pre-release docs table of contents file, i.e. `site/_data/-toc.yml`. - Remove the pre-release docs table of contents mapping entry from `site/_data/toc-mapping.yml`. - Remove all references to the pre-release docs from `site/_config.yml`. -1. Run `NEW_DOCS_VERSION= make gen-docs` (e.g. `NEW_DOCS_VERSION=v1.2.0 make gen-docs` or `NEW_DOCS_VERSION=v1.2.0-beta.1 make gen-docs`). +1. Run `NEW_DOCS_VERSION=v VELERO_VERSION=v make gen-docs` (e.g. `NEW_DOCS_VERSION=v1.2 VELERO_VERSION=v1.2.0 make gen-docs` or `NEW_DOCS_VERSION=v1.2-pre VELERO_VERSION=v1.2.0-beta.1 make gen-docs`). + - Note that: + - **NEW_DOCS_VERSION** defines the version that the docs will be tagged with (i.e. what's in the URL, what shows up in the version dropdown on the site). This should be formatted as either `v1.4` (for a GA release), or `v1.4-pre` (for an alpha/beta/RC). + - **VELERO_VERSION** defines the tag of Velero that any `https://github.com/vmware-tanzu/velero/...` links in the docs should redirect to. 1. Follow the additional instructions at `site/README-JEKYLL.md` to complete the docs generation process. 1. Do a review of the diffs, and/or run `make serve-docs` and review the site. 1. Submit a PR containing the changelog and the version-tagged docs.