Add versioning to autogenerated API docs (#561)

* Add scripts to regenerate the Wiki sidebar doc on new API versions

* Fix generated URLs to not have the .asciidoc suffix

This allows linking to the wiki pages rather than the raw asciidoc file

Author: coro

.github/workflows/publish-versioned-api-ref.yml

@@ -0,0 +1,38 @@
+name: "Publish Versioned API Reference Wiki page"
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish-versioned-api-reference:
+    name: Publish Versioned API Reference Wiki
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout operator codebase
+        uses: actions/checkout@v2
+        with:
+          path: cluster-operator
+      - name: Get the version
+        id: get_version
+        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\//}
+      - name: Checkout wiki codebase
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: wiki
+      - name: Push to wiki
+        run: |
+          cd wiki
+          git config --local user.email "[email protected]"
+          git config --local user.name "github-actions"
+          # Add the versioned API Reference to the Wiki
+          cp ../cluster-operator/docs/api/rabbitmq.com.ref.asciidoc ./API_Reference_${{ steps.get_version.outputs.VERSION }}.asciidoc
+          # Regenerate the ordered list of API Reference docs for the sidebar
+          export REGENERATED_SIDEBAR="$(../cluster-operator/hack/generate-ordered-api-reference-list.sh .)"
+          echo "$REGENERATED_SIDEBAR" > Wiki_Sidebar.md
+          git add ./API_Reference_${{ steps.get_version.outputs.VERSION }}.asciidoc
+          git add ./Wiki_Sidebar.md
+          git commit -m "Publish version ${{ steps.get_version.outputs.VERSION }} API Reference" && git push

.github/workflows/update-api-ref.yml renamed to .github/workflows/update-latest-api-ref.yml

@@ -1,12 +1,12 @@
-name: "Update API Reference Wiki page"
+name: "Update Latest API Reference Wiki page"
 
 on:
   push:
     branches: [ main ]
 
 jobs:
   update-api-reference:
-    name: Update API Reference Wiki
+    name: Update Latest API Reference Wiki
     runs-on: ubuntu-latest
 
     steps:
@@ -24,6 +24,7 @@ jobs:
           cd wiki
           git config --local user.email "[email protected]"
           git config --local user.name "github-actions"
+          # Update the latest API Reference Doc
           cp ../cluster-operator/docs/api/rabbitmq.com.ref.asciidoc ./API_Reference.asciidoc
-          git add .
-          git diff-index --quiet HEAD || git commit -m "Update API Reference" && git push
+          git add ./API_Reference.asciidoc
+          git diff-index --quiet HEAD || git commit -m "Update Latest API Reference" && git push

hack/generate-ordered-api-reference-list.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+set -euo pipefail
+
+wikiDir=$1
+
+generateVersionedEntry() {
+  echo "* [$1](https://github.com/rabbitmq/cluster-operator/wiki/API_Reference_$1)"
+}
+
+generateLatestEntry() {
+  echo "* [Latest](https://github.com/rabbitmq/cluster-operator/wiki/API_Reference)"
+}
+
+lead='^<!--- BEGIN API REFERENCE LIST -->$'
+tail='^<!--- END API REFERENCE LIST -->$'
+
+unorderedlistfile="$(mktemp)"
+orderedlistfile="$(mktemp)"
+
+apiVersions="$(find $wikiDir/API_Reference_* -printf "%f\n" | sed -r 's/API_Reference_(v[0-9]+.[0-9]+.[0-9]+).asciidoc/\1/' | sort -Vr )"
+for version in $apiVersions
+do
+  echo "$(generateVersionedEntry $version)" >> $unorderedlistfile
+done
+
+# Latest API version is a special case, that is always top of the list
+generateLatestEntry > $orderedlistfile
+cat $unorderedlistfile >> $orderedlistfile
+
+sed -e "/$lead/,/$tail/{ /$lead/{p; r $orderedlistfile
+}; /$tail/p; d }"  "$wikiDir/Wiki_Sidebar.md"