docs: versioning (#225)

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

@@ -40,7 +40,8 @@ jobs:
           cd docs
           pip install -r requirements.txt
           pip install --pre -U furo
-          make dirhtml
+          export NUM_RELEASES=5
+          bash makedoc.sh
           cd ./_build/dirhtml/
           cp -r ./ ../../../gen-html
           cd -  # back to ./docs
@@ -53,8 +54,6 @@ jobs:
           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 finetuner.jina.ai > CNAME
           cd ..
           git status

.github/workflows/label-pr.yml

@@ -47,8 +47,10 @@ jobs:
           npm i -g netlify-cli
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-          bash makedoc.sh
-          netlify deploy --dir=_build/dirhtml --alias=${{ env.BRANCH_NAME }} --message="Deploying docs to ${{ env.BRANCH_NAME }} branch"
+          git fetch origin
+          export NUM_RELEASES=2 # only 2 last tags to save build time 
+          bash makedoc.sh development
+          netlify deploy --dir=_build/dirhtml --alias="ft-${{ env.BRANCH_NAME }}" --message="Deploying docs to ${{ env.BRANCH_NAME }} branch"
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN1 }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
@@ -76,4 +78,4 @@ jobs:
         with:
           issue-number: ${{ github.event.pull_request.number }}
           body: |
-            :memo: Docs are deployed on https://${{ env.BRANCH_NAME }}--jina-docs.netlify.app :tada: 
+            :memo: Docs are deployed on https://ft-${{ env.BRANCH_NAME }}--jina-docs.netlify.app :tada: 

docs/_static/main.css

@@ -125,4 +125,16 @@ body[data-theme="auto"] .only-light-line {
 
 body[data-theme="auto"] .only-dark-line {
     display: none !important;
+}
+
+#versions {
+    font-size: .7em;
+    border-radius: 5px;
+    cursor: pointer;
+    background-color: #fff;
+    background-image: linear-gradient(to top, #f9f9f9, #fff 33%);
+    border-color: var(--color-background-border);
+    margin: 1em;
+    outline: none;
+    text-align: center;
 }

docs/_templates/sidebar/brand.html

@@ -14,6 +14,28 @@
   <div class="sd-text-center">
   <a class="github-button" href="https://github.com/jina-ai/finetuner" data-icon="octicon-star" data-show-count="true" aria-label="Star jina-ai/finetuner on GitHub">Star</a>
   </div>
+  <div class="sd-text-center">
+    <select id="versions" onChange="window.location.href=this.value">
+      {% if versions %}
+        {%- for item in versions|reverse %}        
+          {% if item.name == latest_finetuner_version %}
+            {% set new_url = item.url if current_version.name == latest_finetuner_version else item.url | replace('/' + latest_finetuner_version, "") %}
+            {% if current_version.version == item.version %}
+              <option value="{{ new_url }}" 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 }} >{{ item.name }}</option>
+            {% else %}
+              <option value="{{ item.url }}" }} >{{ item.name }}</option>
+            {% endif %}
+          {% endif %}
+        {%- endfor %}
+      {% endif %}
+    </select>
+  </div>
   {% if not theme_sidebar_hide_name %}
   <span class="sidebar-brand-text">{{ docstitle if docstitle else project }}</span>
   {%- endif %}

docs/conf.py

@@ -101,6 +101,7 @@
     'myst_parser',
     'sphinx_design',
     'sphinx_inline_tabs',
+    'sphinx_multiversion',
 ]
 
 myst_enable_extensions = ['colon_fence', 'dollarmath']
@@ -167,7 +168,7 @@
 ogp_use_first_image = False
 ogp_description_length = 300
 ogp_type = 'website'
-ogp_site_name = 'Finetuner Documentation'
+ogp_site_name = f'Finetuner {os.environ.get("SPHINX_MULTIVERSION_VERSION", version)} Documentation'
 
 ogp_custom_meta_tags = [
     '<meta name="twitter:card" content="summary_large_image">',
@@ -190,6 +191,16 @@
     ''',
 ]
 
+def smv_config(string: str):
+    return r'^{}$'.format(string.strip().replace(' ', '|'))
+
+html_context = {
+    'latest_finetuner_version': os.environ.get('LATEST_FINETUNER_VERSION', 'main')
+}
+smv_tag_whitelist = smv_config(os.environ.get('SMV_TAG_WHITELIST', 'v2.4.7'))
+smv_branch_whitelist = smv_config(os.environ.get('SMV_BRANCH_WHITELIST', 'main'))
+smv_remote_whitelist = None
+
 
 def add_server_address(app):
     # This makes variable `server_address` available to docbot.js

docs/makedoc.sh

@@ -2,6 +2,37 @@
 
 set -ex
 
-rm -rf api && make clean
+export NUM_RELEASES=${NUM_RELEASES:-5}
+export DEFAULT_BRANCH='main'
+export BUILD_DIR=_build/dirhtml
 
-make dirhtml
+declare -a ARR_SMV_TAG_WHITELIST=()
+declare -a ARR_SMV_BRANCH_WHITELIST=()
+
+rm -rf api && rm -rf ${BUILD_DIR}
+
+# Might error out with "API Limit exceeds" on local (would need api token), but on CI shouldn't face issues.
+declare -a LAST_N_TAGS=( $(curl -s -H "Accept: application/vnd.github.v3+json" \
+    "https://api.github.com/repos/jina-ai/finetuner/releases?per_page=${NUM_RELEASES}" \
+    | jq -r '.[].tag_name') )
+
+export LATEST_FINETUNER_VERSION="${LAST_N_TAGS[0]}"
+
+if [[ $1 == "development" ]]; then
+  current_branch=$(git branch --show-current)
+  if [[ ${current_branch} != ${DEFAULT_BRANCH} ]]; then
+    ARR_SMV_BRANCH_WHITELIST+=" ${current_branch}"
+  fi
+fi
+
+ARR_SMV_BRANCH_WHITELIST+=" ${DEFAULT_BRANCH}"
+ARR_SMV_TAG_WHITELIST+=" ${LAST_N_TAGS[@]}"
+export SMV_BRANCH_WHITELIST="${ARR_SMV_BRANCH_WHITELIST}"
+export SMV_TAG_WHITELIST="${ARR_SMV_TAG_WHITELIST}"
+
+echo -e "Latest Finetuner Version: ${LATEST_FINETUNER_VERSION}"
+echo -e "Branches to whitelist: ${SMV_BRANCH_WHITELIST}"
+echo -e "Tags to whitelist: ${SMV_TAG_WHITELIST}"
+
+sphinx-multiversion . ${BUILD_DIR}
+mv -v _build/dirhtml/${LATEST_FINETUNER_VERSION}/* _build/dirhtml

docs/requirements.txt

@@ -12,3 +12,5 @@ furo
 myst-parser==0.15.1
 sphinx-design
 sphinx-inline-tabs
+# sphinx-multiversion
+git+https://github.com/Holzhaus/sphinx-multiversion.git