Move V2 API docs to Github Pages (#3874)

pivotalgeorge · web-flow · commit 90ba46629eb9 · 2024-07-12T15:56:12.000-07:00
* Replace v2 apidocs version widget app with a static-generated header on index.html
* Note that the v2 docs will be deployed under capi-release's GitHub Pages via GitHub Actions
diff --git a/.github/workflows/docs_test.yml b/.github/workflows/docs_test.yml
@@ -30,6 +30,9 @@ jobs:
       - uses: ./.github/workflows/composite/setup
         with:
           WORKING_DIRECTORY: docs/v3
+      - name: Render V2 docs
+        working-directory: docs/v2
+        run: ./render.sh
       - name: Run docs tests
         run: |
           bundle config set --local without 'development'
diff --git a/.gitignore b/.gitignore
@@ -28,6 +28,7 @@ test.out
 !/.devcontainer/**/*
 
 #DOCS
+docs/v2/index.html
 
 docs/v3/*.gem
 docs/v3/*.rbc
diff --git a/docs/v2/README.md b/docs/v2/README.md
@@ -1,5 +1,10 @@
 Cloud Foundry v2 API Docs
 =========================
 
-To render these docs locally, run `python3 -m http.server 8000` and view at
-`localhost:8000`.
+To render these docs locally, run:
+```
+./render.sh
+python3 -m http.server 8000
+```
+
+The docs can then be viewed at `localhost:8000`.
diff --git a/docs/v2/index.html.erb b/docs/v2/index.html.erb
@@ -35,6 +35,20 @@
 </head>
 <body>
 <div class="container">
+  <div class="panel panel-info">
+    <div class="panel-heading">
+      <h3 class="panel-title">Version Note:</h3>
+    </div>
+    <div class="panel-body">
+      These docs were last changed with
+      <a href="https://github.com/cloudfoundry/cloud_controller_ng/commit/<%= ENV['DOC_CHANGE_COMMIT'] %>" class="alert-link"><%= ENV['DOC_CHANGE_COMMIT'] %></a>
+      , and therefore they are up-to-date for CAPI version <%= ENV['DOC_CHANGE_VERSION'] %>.
+      The V2 API is considered stable, and further changes are not expected.
+      For previous versions, see the <code>docs/v2</code> directory at
+      <a href="https://github.com/cloudfoundry/cloud_controller_ng/commits/main/config/version_v2" class="alert-link">the desired version</a>
+    </div>
+  </div>
+
   <h1>Cloud Foundry API</h1>
 
   <div class="article">
diff --git a/docs/v2/render.sh b/docs/v2/render.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+
+pushd "$repo_root"
+    export DOC_CHANGE_COMMIT="$(git log -1 --format=format:%h -- docs/v2)"
+    git checkout $DOC_CHANGE_COMMIT -- config/version_v2
+    export DOC_CHANGE_VERSION="$(cat config/version_v2)"
+    git checkout -- config/version_v2
+popd
+
+erb index.html.erb > index.html
