feat: support custom slug per docs version

Author: foosel

.github/workflows/docs.yaml

@@ -41,18 +41,22 @@ jobs:
             mermaid: "1.0.0"
             jinja: "3.1.1"
           - version: "wip/alt-comm"
+            slug: "alt-comm"
             source: "heads"
             python: "3.12"
             sphinx: "8.2.3"
             mermaid: "1.0.0"
             jinja: "3.1.1"
     steps:
-      - name: 🧾 Log event & matrix
+      - name: 🧾 Log event & matrix, determine slug
         run: |
           echo "Event: ${{ github.event_name }} - ${{ toJson(github.event.client_payload) }}"
-          echo "Matrix: ${{ matrix.version }}, ${{ matrix.source }}, ${{ matrix.python }}, ${{ matrix.mermaid }}"
+          echo "Matrix: ${{ matrix.version }}, ${{ matrix.slug }}, ${{ matrix.source }}, ${{ matrix.python }}, ${{ matrix.mermaid }}"
           echo "Formatted ref: ${{ format('refs/{0}/{1}', matrix.source, matrix.version) }}"
 
+          DOC_SLUG="${{ matrix.slug || matrix.version }}"
+          echo "DOC_SLUG=$DOC_SLUG" >> $GITHUB_ENV
+
       - name: 🛡️ Disable AppArmor
         uses: cisagov/action-disable-apparmor@437d94f26a2e4bf8c03acfb500a6afc688b497db # v1.0.0
 
@@ -117,23 +121,23 @@ jobs:
         if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version)
         run: |
           cd ${{ github.workspace }}/docs.octoprint.org/util/versionselector
-          python versionselector.py ${{ github.workspace }}/OctoPrint/docs/ ${{ matrix.version }} ${{ env.OCTOPRINT_VERSION }} ${{ github.workspace }}/versions.json -D mermaid_cmd=${{ github.workspace }}/node_modules/.bin/mmdc -D mermaid_params="-p${{ github.workspace }}/puppeteer-config.json" -D mermaid_output_format=svg -D mermaid_version=
-          echo ".rst-content object[type^='image/']{width: 100%;}" >> ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ matrix.version }}/_static/theme_overrides.css
+          python versionselector.py ${{ github.workspace }}/OctoPrint/docs/ ${{ env.DOC_SLUG }} ${{ env.OCTOPRINT_VERSION }} ${{ github.workspace }}/versions.json -D mermaid_cmd=${{ github.workspace }}/node_modules/.bin/mmdc -D mermaid_params="-p${{ github.workspace }}/puppeteer-config.json" -D mermaid_output_format=svg -D mermaid_version=
+          echo ".rst-content object[type^='image/']{width: 100%;}" >> ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ env.DOC_SLUG }}/_static/theme_overrides.css
 
       #- name: 🔎 Run link check
       #  id: lc
       #  uses: peter-evans/link-checker@v1
       #  with:
-      #    args: -v -r -d ./OctoPrint/docs/_build/html/${{ matrix.version }} ./OctoPrint/docs/_build/html/${{ matrix.version }}
+      #    args: -v -r -d ./OctoPrint/docs/_build/html/${{ env.DOC_SLUG }} ./OctoPrint/docs/_build/html/${{ env.DOC_SLUG }}
       #- name: 🔎 Evaluate link check
       #  run: exit ${{ steps.lc.outputs.exit_code }}
 
       - name: ⬆ Persist build result
         if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version)
         uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.version }}
-          path: ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ matrix.version }}
+          name: ${{ env.DOC_SLUG }}
+          path: ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ env.DOC_SLUG }}
 
   deploy:
     name: Deploy docs

util/versions_from_matrix.py

@@ -21,7 +21,7 @@
 
     versions = dict()
     for version in matrix:
-        name = version["version"]
+        name = version.get("slug", version["version"])
         source = version["source"]
         print("Adding {}/{} to versions.json".format(name, source))