Pull in api docs in build (#3832)

docs/reference/api/README.md

@@ -1,18 +0,0 @@
-
-## View the latest release
-
-The reference documentation for the latest release of the Knative is available
-at [**www.knative.dev**](https://www.knative.dev/docs/reference/).
-
-### Source files
-
-The API source files are located at:
-
-- [Serving API](./serving.md)
-- [Eventing API](./eventing/eventing.md)
-
-### Generating API docs
-
-See the
-[API build instructions](https://www.knative.dev/help/maintainer/building-api-output)
-in the Knative documentation maintainer section.

docs/reference/api/eventing-api.md

@@ -0,0 +1 @@
+This file is updated to the correct version from the eventing repo (docs/eventing-api.md) during the build.

docs/reference/api/eventing/README.md

@@ -1,10 +0,0 @@
----
-title: "Knative Eventing Component"
-linkTitle: "Eventing API"
-weight: 20
-type: "docs"
-aliases:
-   - /docs/reference/eventing/eventing
----
-
-{{< readfile file="eventing.md" >}}

docs/reference/api/serving-api.md

@@ -1,10 +1 @@
----
+This file is updated to the correct version from the serving repo (docs/serving-api.md) during the build.
-title: "Knative Serving Component"
-linkTitle: "Serving API"
-weight: 10
-type: "docs"
-aliases:
-   - /docs/reference/serving-api
----
-
-{{< readfile file="serving.md" >}}

hack/build.sh

@@ -21,7 +21,8 @@ set -x
 #    Order matters :-), Most recent first.
 VERSIONS=("0.23" "0.22" "0.21")
 # 3) For now, set branches too. (This will go away when all branches are release-NN).
-BRANCHES=("mkrelease-0.23" "mkrelease-0.22" "mkrelease-0.22")
+DOCS_BRANCHES=("mkrelease-0.23" "mkrelease-0.22" "mkrelease-0.22")
+RELEASE_BRANCHES=("v0.23.0" "v0.22.0" "v0.21.0")
 REPOS=("julz" "julz" "julz")
 # 4) PR the result to main.
 # 5) Party.
@@ -31,8 +32,8 @@ community_repo=${COMMUNITY_REPO:-knative}
 latest=${VERSIONS[0]}
 previous=("${VERSIONS[@]:1}")
 
-rm -rf temp
+readonly TEMP="$(mktemp -d)"
-mkdir temp
+readonly SITE=$PWD/site
 rm -rf site/
 
 if [ "$BUILD_VERSIONS" == "no" ]; then
@@ -40,13 +41,18 @@ if [ "$BUILD_VERSIONS" == "no" ]; then
   mkdocs build -f mkdocs.yml -d site/docs
 else
   # Versioning: pre-release (HEAD): docs => development/
-  mkdocs build -f mkdocs.yml -d site/development
+  cp -r . $TEMP/docs-main
+  curl -f --show-error https://raw.githubusercontent.com/knative/serving/main/docs/serving-api.md -s > "$TEMP/docs-main/docs/reference/api/serving-api.md"
+  curl -f --show-error https://raw.githubusercontent.com/knative/eventing/main/docs/eventing-api.md -s > "$TEMP/docs-main/docs/reference/api/eventing-api.md"
+  pushd "$TEMP/docs-main"; mkdocs build -f mkdocs.yml -d $SITE/development; popd
 
   # Latest release branch to /docs
-  git clone --depth 1 -b ${BRANCHES[0]} https://github.com/${REPOS[0]}/docs "temp/docs-$latest"
+  git clone --depth 1 -b ${DOCS_BRANCHES[0]} https://github.com/${REPOS[0]}/docs "$TEMP/docs-$latest"
-  pushd "temp/docs-$latest"
+  # This won't work until release 0.24 is cut in serving and eventing.
-  KNATIVE_VERSION=$latest mkdocs build -d ../../site/docs
+  # TODO: Uncomment this when 0.24 is cut.
-  popd
+  # curl -f --show-error https://raw.githubusercontent.com/knative/serving/${RELEASE_BRANCHES[0]}/docs/serving-api.md -s > "$TEMP/docs-$latest/docs/reference/api/serving-api.md"
+  # curl -f --show-error https://raw.githubusercontent.com/knative/eventing/${RELEASE_BRANCHES[0]}/docs/eventing-api.md -s > "$TEMP/docs-$latest/docs/reference/api/eventing-api.md"
+  pushd "$TEMP/docs-$latest"; KNATIVE_VERSION=$latest mkdocs build -d $SITE/docs; popd
 
   # Previous release branches release-$version to /v$version-docs
   versionjson=""
@@ -54,15 +60,15 @@ else
     version=${previous[$i]}
     versionjson+="{\"version\": \"v$version-docs\", \"title\": \"v$version\", \"aliases\": [\"\"]},"
 
-    # This is a hack to make old sites links be handle by netlify redirects, we want the drop down but not the content yet
+    # This is a hack to make old sites links be handled by netlify redirects, we want the drop down but not the content yet
-    #git clone --depth 1 -b ${BRANCHES[$i+1]} https://github.com/${REPOS[i+1]}/docs "temp/docs-$version"
+    # git clone --depth 1 -b ${DOCS_BRANCHES[$i+1]} https://github.com/${REPOS[i+1]}/docs "$TEMP/docs-$version"
-    #pushd "temp/docs-$version"
+    # curl -f --show-error https://raw.githubusercontent.com/knative/serving/${RELEASE_BRANCHES[i+1]}/docs/serving-api.md -s > "$TEMP/docs-$version/docs/reference/api/serving-api.md"
-    #KNATIVE_VERSION=$version VERSION_WARNING=true mkdocs build -d "../../site/v$version-docs"
+    # curl -f --show-error https://raw.githubusercontent.com/knative/eventing/${RELEASE_BRANCHES[i+1]}/docs/eventing-api.md -s > "$TEMP/docs-$version/docs/reference/api/eventing-api.md"
-    #popd
+    # pushd "$TEMP/docs-$version"; KNATIVE_VERSION=$version VERSION_WARNING=true mkdocs build -d "$SITE/v$version-docs"; popd
   done
 
   # Set up the version file to point to the built docs.
-  cat << EOF > site/versions.json
+  cat << EOF > $SITE/versions.json
   [
     {"version": "docs", "title": "v$latest", "aliases": [""]},
     $versionjson
@@ -73,7 +79,9 @@ fi
 
 if [ -z "$SKIP_BLOG" ]; then
   # Clone out the website and community repos for the hugo bits.
+  # This can be removed if/when we move the blog and community stuff to mkdocs.
   # TODO(jz) Cache this and just do a pull/update/use siblings for local dev flow.
+  rm -rf temp
   git clone --depth 1 https://github.com/knative/website temp/website
   pushd temp/website; git submodule update --init --recursive --depth 1; popd
   git clone -b ${community_branch} --depth 1 https://github.com/${community_repo}/community temp/community
@@ -89,12 +97,13 @@ if [ -z "$SKIP_BLOG" ]; then
   cp -r temp/community/* temp/website/content/en/community/contributing/
   rm -r temp/website/content/en/community/contributing/elections/2021-TOC # Temp fix for markdown that confuses hugo.
 
-  # See https://github.com/knative/website/blob/main/scripts/processsourcefiles.sh#L125
-  # For the reasoning behind all this.
-  echo 'Converting all links in GitHub source files to Hugo supported relative links...'
   # Setup postcss to be in the PATH
   PATH=${PATH}:${PWD}/node_modules/.bin
   pushd temp/website
+
+  # See https://github.com/knative/website/blob/main/scripts/processsourcefiles.sh#L125
+  # For the reasoning behind all this.
+  echo 'Converting all links in GitHub source files to Hugo supported relative links...'
   # Convert relative links to support Hugo
   find . -type f -path '*/content/*.md' ! -name '*_index.md' ! -name '*index.md' ! -name '*README.md' \
     ! -name '*serving-api.md' ! -name '*eventing-contrib-api.md' ! -name '*eventing-api.md' \
@@ -145,7 +154,7 @@ cat << EOF > site/index.html
 EOF
 
 # Clean up
-rm -rf temp
+rm -rf $TEMP
 
 if [ "$1" = "serve" ]; then
   pushd site

mkdocs.yml

@@ -230,8 +230,8 @@ nav:
         - IoT core: eventing/samples/iot-core/README.md
     # Reference docs
     - Reference:
-      - Serving: reference/api/serving.md
+      - Serving: reference/api/serving-api.md
-      - Eventing: reference/api/eventing/eventing.md
+      - Eventing: reference/api/eventing-api.md
     # Client
     - Client:
       - Overview: client/README.md
@@ -288,7 +288,6 @@ plugins:
         # (either the include shortcode or not-converted-yet tabs).
         - snippets/*
         - smoketest.md
-        - "*/serving-api.md" # shortcode to serving.md
         - "*/_index.md" # pretty much all shortcodes
   - awesome-pages:
       filename: ".index"