WIP

Author: bclement-ocp

.github/workflows/documentation.yml

@@ -8,7 +8,15 @@ name: Documentation
 # - deploy_docs only run on the next branch when code is pushed. It retrieve
 # the ocaml and sphinx documentation and deploy them on the gh-pages branch
 
-on: [push, pull_request]
+on:
+  push:
+    tags:
+      - "v*.*.*"
+    branches:
+      - next
+      - main
+      - multidoc
+  pull_request:
 
 env:
   OCAML_DEFAULT_VERSION: 4.10.0
@@ -115,33 +123,38 @@ jobs:
   deploy_docs:
     name: Deploy documentation
 
-    if: github.ref == 'refs/heads/main'
+    if: ${{ github.event_name == 'push' }}
 
     needs:
       - ocaml_docs
       - sphinx_docs
 
     runs-on: ubuntu-latest
     steps:
+      - name: Determine version name
+        id: version-name
+        run: |
+          echo "::set-output name=target::${GITHUB_REF#*/*/}"
+
       # Retrieve ocaml documentation artifact
       - name: Download ocaml documentation
         uses: actions/download-artifact@v4
         with:
           name: ocaml_doc
-          path: _build/odoc/dev
+          path: _build/odoc/${{ steps.version-name.outputs.target }}
 
       # Retrieve sphinx documentation artifact
       - name: Download sphinx documentation
         uses: actions/download-artifact@v4
         with:
           name: sphinx_doc
-          path: _build
+          path: _build/${{ steps.version-name.outputs.target }}
 
       - name: Add files to bypass nojekyll
         run: |
           touch _build/.nojekyll
           touch _build/odoc/.nojekyll
-          touch _build/odoc/dev/.nojekyll
+          touch _build/odoc/${{ steps.version-name.outputs.target }}/.nojekyll
 
       # Deploy files contain in _build directory on gh-pages branch
       - name: deploy-doc

docs/sphinx_docs/_static/js/versions.js

@@ -0,0 +1,29 @@
+function renderVersions(versions) {
+  return `
+  <dl>
+    <dt>Versions</dt>${ versions.active.map((version) => `
+    <dd ${ version.slug == versions.current.slug ? 'class="rtd-current-item"' : '' }>
+      <a href="${ version.url }">${ version.slug }</a>
+    </dd>
+    `).join("\n")}
+  </dl>
+  `;
+}
+
+document.addEventListener('DOMContentLoaded', function () {
+  $.getJSON('_static/versions.json', (versions) => {
+    console.log(versions);
+    document.body.insertAdjacentHTML("beforeend", `
+    <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="Versions">
+      <span class="rst-current-version" data-toggle="rst-current-version">
+        <span class="fa fa-book"> Current version</span>
+        v: ${ versions.current.slug }
+        <span class="fa fa-caret-down"></span>
+      </span>
+      <div class="rst-other-versions">
+        ${renderVersions(versions)}
+      </div>
+    </div>
+    `);
+  });
+});

docs/sphinx_docs/_static/versions.json

@@ -0,0 +1,7 @@
+{
+  "current": {"url": "dev", "slug": "next"},
+  "active": [
+    {"url": "dev", "slug": "next"},
+    {"url": "v2.5.4", "slug": "2.5.4"}
+  ]
+}

docs/sphinx_docs/conf.py

@@ -70,3 +70,11 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+# -- Context population (version management and more) ------------------------
+
+html_js_files = ['js/versions.js']
+html_context = {
+    'current_version': 'dev',
+    'versions': [['2.5.4', 'v2.5.4']],
+}