docs: add versioned docs (#5310)

.github/workflows/build-old-docs.yml

@@ -0,0 +1,124 @@
+name: Build old docs
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_token:
+        description: 'Your release token'
+        required: true
+      triggered_by:
+        description: 'CD | TAG | MANUAL'
+        required: false
+        default: MANUAL
+      package:
+        description: The name of the repo to build documentation for.
+        type: string
+        default: jina
+      repo_owner:
+        description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
+        type: string
+        default: jina-ai
+      pages_branch:
+        description: Branch that Github Pages observes
+        type: string
+        default: gh-pages
+      git_config_name:
+        type: string
+        default: Jina Dev Bot
+      git_config_email:
+        type: string
+        default: [email protected]
+
+jobs:
+  token-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check release token
+        id: token-check
+        run: | 
+          touch SUCCESS
+        if: inputs.release_token == env.release_token
+        env:
+          release_token: ${{ secrets.JINA_CORE_RELEASE_TOKEN }}
+      - name: Fail release token
+        run: |
+          [[ -f SUCCESS ]]
+      - name: Get versions
+        id: get_versions
+        run: |
+          printf "versions=" >> $GITHUB_OUTPUT
+          curl https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/master/docs/_versions.json >> $GITHUB_OUTPUT
+    outputs:
+      versions: ${{ steps.get_versions.outputs.versions }}
+
+  build-doc:
+    needs: token-check
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.token-check.outputs.versions) }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+          ref: ${{ matrix.version }}
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.7'
+      - name: Get latest templates
+        run: |
+          git show --summary
+          echo "Get latest sidebar brand template"
+          wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/master/docs/_templates/sidebar/brand.html
+          mv ./brand.html ./docs/_templates/sidebar/brand.html
+      - name: Install dependencies
+        run: |
+          pip install .[devel]
+          cd docs
+          pip install -r requirements.txt
+          pip install --pre -U furo
+          pip install sphinx-markdown-tables==0.0.17
+      - name: Sphinx Build
+        run: |
+          cd docs
+          bash makedoc.sh local-only
+      - name: Package build into artifact
+        run: |
+          mv ./docs/_build/dirhtml ./${{ matrix.version }}
+          zip -r /tmp/build.zip ./${{ matrix.version }}/*
+      - name: Upload built html
+        uses: actions/upload-artifact@v3
+        with:
+            name: ${{ matrix.version }}
+            path: /tmp/build.zip
+            retention-days: 1
+
+  push-docs:
+    runs-on: ubuntu-latest
+    needs: build-doc
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+          ref: ${{ inputs.pages_branch }}
+      - uses: actions/download-artifact@v3
+        with:
+          path: /tmp/artifacts
+      - name: Clear old builds
+        run: |
+          cd docs
+          for i in $(ls /tmp/artifacts); do git rm -rf "$i" || true; done
+      - name: In with new builds
+        run: |
+          cd docs
+          for i in $(ls /tmp/artifacts); do unzip "/tmp/artifacts/$i/build.zip"; done
+          rm _versions.json || true
+          wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/master/docs/_versions.json
+      - name: Push it up!
+        run: |
+          git config --local user.email "${{ inputs.git_config_email }}"
+          git config --local user.name "${{ inputs.git_config_name }}"
+          git show --summary
+          git add . && git commit -m "chore(docs): update old docs due to ${{github.event_name}} on ${{github.repository}}"
+          git push origin

.github/workflows/force-docs-build.yml

@@ -10,6 +10,28 @@ on:
         description: 'CD | TAG | MANUAL'
         required: false
         default: MANUAL
+      build_old_docs:
+        description: 'Whether to build old docs (TRUE | FALSE)'
+        type: string
+        default: 'FALSE'
+      package:
+        description: The name of the repo to build documentation for.
+        type: string
+        default: jina
+      repo_owner:
+        description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
+        type: string
+        default: jina-ai
+      pages_branch:
+        description: Branch that Github Pages observes
+        type: string
+        default: gh-pages
+      git_config_name:
+        type: string
+        default: Jina Dev Bot
+      git_config_email:
+        type: string
+        default: [email protected]
 
 jobs:
   token-check:
@@ -26,44 +48,66 @@ jobs:
         run: |
           [[ -f SUCCESS ]]
 
-
-  regular-release:
+  build-and-push-latest-docs:
     needs: token-check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2.5.0
+      - uses: actions/checkout@v3
         with:
-          fetch-depth: 0
+          fetch-depth: 1
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.7
-      - name: Build doc and push to gh-pages
+          python-version: '3.7'
+      - name: Install Dependencies
         run: |
-          git config --local user.email "[email protected]"
-          git config --local user.name "Jina Dev Bot"
           pip install .[devel]
-          mkdir gen-html
           cd docs
           pip install -r requirements.txt
           pip install --pre -U furo
-          export NUM_RELEASES=2
+          pip install sphinx-markdown-tables==0.0.17
+      - name: Sphinx Build
+        run: |
+          cd docs
           bash makedoc.sh local-only
-          cd ./_build/dirhtml/
-          cp -r ./ ../../../gen-html
-          cd -  # back to ./docs
-          cd ..
-          git checkout -f gh-pages
-          git rm -rf ./docs
-          mkdir -p docs
-          cd gen-html
-          cp -r ./ ../docs
-          cd ../docs
-          ls -la
-          touch .nojekyll
-          cp 404/index.html 404.html
-          sed -i 's/href="\.\./href="/' 404.html # fix asset urls that needs to be updated in 404.html
-          echo docs.jina.ai > CNAME
+          mv ./_build/dirhtml /tmp/gen-html
           cd ..
-          git status
-          git add docs && git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
-          git push --force origin gh-pages
+      - name: Checkout to GH pages branch (${{ inputs.pages_branch }})
+        run: |
+          git fetch origin ${{ inputs.pages_branch }}:${{ inputs.pages_branch }} --depth 1
+          git checkout -f ${{ inputs.pages_branch }}
+          git reset --hard HEAD
+      - name: Small config stuff
+        run: |
+          touch /tmp/gen-html/.nojekyll
+          cp ./docs/_versions.json /tmp/gen-html/_versions.json
+          cp ./docs/CNAME /tmp/gen-html/CNAME
+          cp /tmp/gen-html/404/index.html /tmp/gen-html/404.html
+          sed -i 's/href="\.\./href="/' /tmp/gen-html/404.html # fix asset urls that needs to be updated in 404.html
+      - name: Moving old doc versions
+        run: |
+          cd docs
+          for i in $(cat _versions.json | jq '.[].version' | tr -d '"'); do mv "$i" /tmp/gen-html; done
+      - name: Swap in new docs
+        run: |
+          rm -rf ./docs
+          mv /tmp/gen-html ./docs
+      - name: Push it up!
+        run: |
+          git config --local user.email "${{ inputs.git_config_email }}"
+          git config --local user.name "${{ inputs.git_config_name }}"
+          git show --summary
+          git add ./docs && git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
+          git push origin ${{ inputs.pages_branch }}
+
+  build-old-docs:
+    needs: build-and-push-latest-docs
+    runs-on: ubuntu-latest
+    if: inputs.build_old_docs == 'TRUE'
+    steps:
+      - uses: benc-uk/workflow-dispatch@v1
+        with:
+          workflow: Build old docs
+          token: ${{ secrets.JINA_DEV_BOT }}
+          inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
+        env:
+          release_token: ${{ secrets.JINA_CORE_RELEASE_TOKEN }}

.github/workflows/tag.yml

@@ -66,7 +66,7 @@ jobs:
         with:
           workflow: Manual Docs Build
           token: ${{ secrets.JINA_DEV_BOT }}
-          inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
+          inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG", "build_old_docs": "TRUE"}'
         env:
           release_token: ${{ secrets.JINA_CORE_RELEASE_TOKEN }}
 

docs/_templates/sidebar/brand.html

@@ -16,26 +16,33 @@
   {%- endif %}
   {% endblock brand_content %}
 </a>
+<script>
+  function setPrefix(prefix){
+    window.sessionStorage.setItem("version-select-index", document.getElementsByClassName("version-select")[0].selectedIndex);
+    window.location.href = prefix
+  }
+</script>
+<script defer>
+  fetch(`https://${window.location.host}/_versions.json`)
+  .then((resp) => resp.json())
+  .then((data) => {
+    var versionSelector = document.getElementsByClassName("version-select")[0]
+    for(var i = 0; i < data.length; i++){
+      var option = document.createElement("option");
+      option.innerHTML = data[i].version;
+      option.value = "/" + data[i].version;
+      versionSelector.appendChild(option);
+    }
+
+    if(window.sessionStorage.getItem('version-select-index')){
+      versionSelector.selectedIndex = window.sessionStorage.getItem('version-select-index');
+    }
+  })
+  .catch((err) => console.log(err));
+</script>
 <div class="sd-d-flex-row sd-align-major-spaced">
   <a class="github-button" href="https://github.com/jina-ai/jina" data-icon="octicon-star" data-show-count="true" aria-label="Star jina-ai/jina on GitHub" style="opacity: 0;">Star</a>
-  {% if versions %}
-  <select onChange="window.location.href=this.value" class="version-select">
-      {%- for item in versions|reverse %}
-        {% if item.name == latest_jina_version %}
-          {% set new_url = item.url if current_version.name == latest_jina_version else item.url | replace('/' + latest_jina_version, "") %}
-          {% if current_version.version == item.version %}
-            <option value="{{ new_url }}" selected="selected" >latest ({{ item.name }})</option>
-          {% else %}
-            <option value="{{ new_url }}" >latest({{ item.name }})</option>
-          {% endif %}
-        {% else %}
-          {% if current_version.version == item.version %}
-            <option value="{{ item.url }}" selected="selected" >{{ item.name }}</option>
-          {% else %}
-            <option value="{{ item.url }}" >{{ item.name }}</option>
-          {% endif %}
-        {% endif %}
-      {%- endfor %}
+  <select onChange="setPrefix(this.value)" class="version-select">
+    <option value="/">latest</option>
   </select>
-  {% endif %}
-</div>
+</div>

docs/_versions.json

@@ -0,0 +1 @@
+[{"version": "v3.11.0"}, {"version": "v3.10.1"}, {"version": "v3.9.3"}, {"version": "v3.8.4"}, {"version": "v3.7.14"}, {"version": "v3.6.16"}, {"version": "v3.5.0"}, {"version": "v3.4.11"}]

scripts/prepend_version_json.py

@@ -0,0 +1,21 @@
+from typing import List
+import argparse
+import json
+
+parser = argparse.ArgumentParser(prog="Prepender docs/_versions.json")
+parser.add_argument(
+    "--version",
+    type=str,
+    help="The version we wish to prepend (e.g. v0.18.0)",
+    required=True,
+)
+args = parser.parse_args()
+
+with open("./docs/_versions.json") as f:
+    versions: List[dict] = json.load(f)
+    element = {k: v for k, v in args._get_kwargs()}
+    if element != versions[0]:
+        versions.insert(0, element)
+
+with open("./docs/_versions.json", "w") as f:
+    json.dump(versions, f)

scripts/release.sh

@@ -75,6 +75,10 @@ export RELEASE_VER=$(sed -n '/^__version__/p' $INIT_FILE | cut -d \' -f2)
 LAST_VER=$(git tag -l | sort -V | tail -n1)
 printf "last version: \e[1;32m$LAST_VER\e[0m\n"
 
+# Update new _versions.json if necessary
+python ./scripts/prepend_version_json.py --version "v$RELEASE_VER"
+git add ./docs/_versions.json
+
 if [[ $1 == "final" ]]; then
   printf "this will be a final release: \e[1;33m$RELEASE_VER\e[0m\n"