docs: Add versioning to documentation

.github/workflows/docs.yaml

@@ -17,6 +17,9 @@ on:
         - dryrun
         required: true
         default: dryrun
+      version:
+        description: 'Version tag X.X.X (required if target is main)'
+        required: false
   schedule:
     - cron: '0 15 * * SUN'
 
@@ -36,46 +39,35 @@ jobs:
 
   docs_build:
     name: Build Documentation
+    needs: [pixi_lock]
     runs-on: 'macos-latest'
     timeout-minutes: 120
     env:
       DISPLAY: ":99.0"
+      VERSION: ${{ inputs.version }}
     steps:
+      - name: Validate version
+        if: ${{ inputs.target == 'main' }}
+        run: |
+          if [[ -z "$VERSION" || ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "❌ 'version' is required and must match format X.X.X (e.g. 0.11.1) when target is 'main'"
+            exit 1
+          fi
       - uses: holoviz-dev/holoviz_tasks/pixi_install@v0
         with:
           environments: docs
       - name: Build documentation
         run: pixi run -e docs docs-build
-      - name: Set and echo git ref
-        id: vars
-        run: |
-          echo "Deploying from ref ${GITHUB_REF#refs/*/}"
-          echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
       - name: report failure
         if: failure()
         run: cat /tmp/sphinx-*.log | tail -n 100
-      - name: Deploy dev
-        uses: peaceiris/actions-gh-pages@v4
-        if: |
-          (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'dev') ||
-          (github.event_name == 'push' && (contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
-        with:
-          personal_token: ${{ secrets.ACCESS_TOKEN }}
-          external_repository: holoviz-dev/hvplot
-          publish_dir: ./builtdocs
-          force_orphan: true
-          exclude_assets: '.doctrees'
-      - name: Deploy main
-        if: |
-          (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'main') ||
-          (github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
-        uses: peaceiris/actions-gh-pages@v4
+      - uses: holoviz-dev/holoviz_tasks/docs-publish@docs_publish
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./builtdocs
-          cname: hvplot.holoviz.org
-          force_orphan: true
-          exclude_assets: '.doctrees'
+          s3-url: s3://hvplot.holoviz.org
+          s3-cloudfront-id: E13QSRL36ILGWH
+          s3-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          s3-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          version: ${{ inputs.version }}
 
   pip_build_docs:
     name: Build Documentation (pip)

doc/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+  {
+    "version": "dev",
+    "url": "https://hvplot-test.holoviz.org/en/docs/dev/"
+  },
+  {
+    "name": "0.11.3 (latest)",
+    "version": "0.11.3",
+    "url": "https://hvplot-test.holoviz.org/en/docs/latest/",
+    "preferred": true
+  }
+]

doc/conf.py

@@ -36,9 +36,14 @@
 html_js_files = [
     'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js',
 ]
-
+switcher_version = (
+    os.getenv('VERSION') or 'dev'
+    if any(pr in hvplot.__version__ for pr in ('a', 'b', 'rc', 'dev'))
+    else version
+)
 html_theme_options.update(  # noqa
     {
+        'navbar_start': ['navbar-logo', 'version-switcher'],
         'use_edit_page_button': True,
         'github_url': 'https://github.com/holoviz/hvplot',
         'icon_links': [
@@ -60,6 +65,11 @@
         ],
         'pygments_dark_style': 'material',
         # 'announcement': "hvPlot 0.11 has just been released! Checkout the <a href='https://blog.holoviz.org/posts/hvplot_release_0.11/'>blog post</a> and support hvPlot by giving it a 🌟 on <a href='https://github.com/holoviz/hvplot'>Github</a>.",
+        'switcher': {
+            'json_url': 'https://hvplot-test.holoviz.org/switcher.json',
+            'version_match': switcher_version,
+        },
+        'show_version_warning_banner': True,
     }
 )
 

pixi.toml

@@ -248,6 +248,7 @@ _docs-install = 'python -m pip install --no-deps --disable-pip-version-check -e
 # Depends on _docs-install instead of install as install
 # in the default environment
 docs-build = { depends-on = ["_docs-install", "docs-build-sphinx"] }
+docs-server = 'python -m http.server 5500 --directory ./builtdocs'
 
 # ================== BUILD ====================