change scripts/docs to generate one docs site per major.minor (#2473)

Signed-off-by: Steve Kriss <krisss@vmware.com>

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.

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

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.

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
   <a href="{{latest_url}}">latest version</a>.
   </p>
-{% 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' %}
   <p>
   <i class="fa fa-exclamation-triangle" aria-hidden="true"></i>
   This is the documentation for the latest pre-production version of Velero. Both code and docs may be

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/<pre-release-version>`.
     - Delete the pre-release docs table of contents file, i.e. `site/_data/<pre-release-version>-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=<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<major.minor> VELERO_VERSION=v<full-version> 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.