support multiple versions of documents (spidernet-io#2217)

Signed-off-by: tao.yang <[email protected]>

.github/workflows/call-release-doc.yaml

@@ -9,10 +9,6 @@ on:
       submit:
         required: true
         type: string
-    outputs:
-      artifact:
-        description: "name of artifact"
-        value: website_package_artifact
   # --- call by manual
   workflow_dispatch:
     inputs:
@@ -21,6 +17,7 @@ on:
         required: true
         default: main
 
+
 permissions: write-all
 
 env:
@@ -31,26 +28,22 @@ env:
   PR_REVIWER: weizhoublue
 
 jobs:
-  prepare_doc:
-    name: prepare doc
+  release_doc:
     runs-on: ubuntu-latest
-    outputs:
-      ref: ${{ steps.get_ref.outputs.ref }}
-      submit: ${{ steps.get_ref.outputs.submit }}
     steps:
       - name: Get Ref
         id: get_ref
         run: |
           pwd
           ls
-          if ${{ inputs.ref != '' }}; then
-              echo "call by workflow_call"
-              echo ::set-output name=ref::${{ inputs.ref }}
-              echo ::set-output name=submit::${{ inputs.submit }}
-          elif ${{ github.event_name == 'workflow_dispatch' }} ; then
+          if ${{ github.event_name == 'workflow_dispatch' }}; then
               echo "call by workflow_dispatch"
-              echo ::set-output name=ref::${{ github.event.inputs.ref }}
-              echo ::set-output name=submit::true
+              echo "REF=${{ github.event.inputs.ref }}" >> $GITHUB_ENV
+              echo "SUBMIT=true" >> $GITHUB_ENV
+          elif ${{ inputs.ref != '' }}; then
+              echo "call by workflow_call"
+              echo "REF=${{ inputs.ref }}" >> $GITHUB_ENV
+              echo "SUBMIT=${{ inputs.submit }}" >> $GITHUB_ENV
           else
               echo "unexpected event: ${{ github.event_name }}"
               exit 1
@@ -59,57 +52,66 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@v3
         with:
-          ref: ${{ steps.get_ref.outputs.ref }}
-
-      - name: Build Site
-        run: |
-          make build_doc
-
-      - name: Upload Artifact
-        uses: actions/[email protected]
-        with:
-          name: website_package_artifact
-          path: docs/site.tar.gz
-          retention-days: 0
-          if-no-files-found: error
-
-  create_pr:
-    name: Create PR
-    needs: prepare_doc
-    if: ${{ needs.prepare_doc.outputs.submit == 'true' }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ env.MERGE_BRANCH }}
+          fetch-depth: 0
+          ref: ${{ env.REF }}
 
-      - name: backup charts
+      - name: Extract Version
+        id: extract
         run: |
-          rm -rf ./_backupCharts
-          mkdir ./_backupCharts
-          cp -f ${{ env.DEST_DIRECTORY }}/index.yaml ./_backupCharts
-          cp -rf ${{ env.DEST_DIRECTORY }}/charts ./_backupCharts/charts
-          rm -rf ${{ env.DEST_DIRECTORY }}
-          mkdir ${{ env.DEST_DIRECTORY }}
-
-      - name: Download Artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: site_artifact
-          path: ${{ env.DEST_DIRECTORY }}
+          if ! grep -E "^[[:space:]]*v[0-9]+.[0-9]+.[0-9]+[[:space:]]*$" VERSION &>/dev/null ; then
+            echo "not a release version, skip generating doc."
+            cat VERSION
+            echo "SKIP_ALL_JOB=true" >> $GITHUB_ENV
+            exit 0
+          fi
+          # for example v0.6.1, the build's documentation version is v0.6
+          docVersion=` cat VERSION  | tr -d ' ' | tr -d '\n' | grep -Eo "v[0-9]+\.[0-9]+" `
+          if [ -n "${docVersion}" ]; then
+              echo "the version intercepted from the branch is: ${docVersion}"
+          else
+              echo "error, failed to get version." && exit 1
+          fi
+          git checkout -f ${{ env.MERGE_BRANCH }}
+          echo "Switch to the branch:${{ env.MERGE_BRANCH }} where the document is located"
+          ls
+          if [ -e "docs/${docVersion}" ]; then
+              echo "doc version:${docVersion} already exists, just update it."
+              echo "SET_LATEST=false" >> $GITHUB_ENV
+          else
+              echo "The doc version:${docVersion} does not exist yet, while generating the doc and set it to latest"
+              echo "SET_LATEST=true" >> $GITHUB_ENV
+          fi
+          echo "the doc version is: ${docVersion}"
+          echo "DOCS_TAG=${docVersion}" >> $GITHUB_ENV
 
-      - name: Untar Artifact And Restore Charts
+      - name: build doc
+        id: build_doc
+        if: ${{ env.SKIP_ALL_JOB != 'true' }}
         run: |
-          cd ${{ env.DEST_DIRECTORY }}
-          tar -xzvf site.tar.gz
-          rm -f site.tar.gz
-          cp -rf ../_backupCharts/* ./
-          rm -rf ../_backupCharts
+          git checkout ${{ env.REF }}
+          ls
+          echo "switch to the release version branch ${{ env.REF }}"
+          pip install mkdocs==1.5.2 mike==1.1.2 mkdocs-material==8.5.11
+          git config user.email "[email protected]"
+          git config user.name "robot"
+          cp ./docs/mkdocs.yml ./
+          if ${{ env.SET_LATEST == 'true' }} ;then
+              echo "generate doc version:${{ env.DOCS_TAG }} and set to latest."
+              mike deploy --rebase --prefix ${{ env.DEST_DIRECTORY }} -b ${{ env.MERGE_BRANCH }} --update-aliases ${{env.DOCS_TAG }} latest
+              mike set-default --prefix ${{ env.DEST_DIRECTORY }} -b ${{ env.MERGE_BRANCH }} latest
+          else
+              echo "the version:${{ env.DOCS_TAG }} of the doc does not need to be set to the latest."
+              mike deploy --rebase --prefix ${{ env.DEST_DIRECTORY }} -b ${{ env.MERGE_BRANCH }} ${{ env.DOCS_TAG }}
+          fi
+          rm -rf ./site
+          rm -rf ./mkdocs.yml
+          git checkout -f  ${{ env.MERGE_BRANCH }}
+          echo "Push a doc version: ${{ env.DOCS_TAG }} from branch: ${{ env.REF }}, update it to latest: ${{ env.SET_LATEST }} "
 
       # Allow auto-merge on general
       - name: Create Pull Request
         id: create_pr
+        if: ${{ env.SUBMIT == 'true' }}
         uses: peter-evans/[email protected]
         with:
           title: "robot update website from ${{ needs.prepare_doc.outputs.ref }} to branch ${{ env.MERGE_BRANCH }} "

docs/mkdocs.yml

@@ -6,6 +6,7 @@ repo_url: https://github.com/spidernet-io/spiderpool
 remote_branch: github_pages
 theme:
   name: readthedocs
+  custom_dir: docs/overrides
   # The maximum depth of the navigation tree in the sidebar
   navigation_depth: 2
   palette:
@@ -22,6 +23,10 @@ plugins:
   - tags
   - search
 
+extra:
+  version:
+    provider: mike
+
 markdown_extensions:
   - meta
   - toc

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}