Multiversion docs (#30)

* Build docs for all versions * Update notification banner
TrossenRobotics · Dec 9, 2024 · fa1b020 · fa1b020
1 parent 309a39e
commit fa1b020
Show file tree

Hide file tree

Showing 6 changed files with 121 additions and 34 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -2,34 +2,56 @@ name: Build and Deploy to GitHub Pages
 
 on:
   workflow_dispatch:
-  pull_request:
   push:
     branches:
-      - main
+      - '1.0'
+      - '2.0'
 
 jobs:
   deploy:
-    if: ${{ github.event_name == 'push' }}
     runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
     steps:
+
       - uses: actions/checkout@v3
         with:
-          fetch-depth: 0
-          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.8'
           cache: 'pip'
+
       - name: Install Dependencies
         run: |
           python -m pip install --upgrade pip
           pip install --upgrade --requirement ./requirements.txt
-      - name: Build Site
-        run: cd docs && make html
-      - name: Deploy Site
-        if: ${{ success() }}
-        uses: peaceiris/actions-gh-pages@v3
+
+      - name: Build Multiversion Docs
+        run: |
+          git fetch --all
+          git checkout 1.0
+          git checkout 2.0
+          git checkout main
+          cd docs
+          make multiversion
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'docs/_build/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/_build/html/
+          token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,20 +1,18 @@
-# Minimal makefile for Sphinx documentation
-#
+SOURCE  = .
+OUT     = _build
+BUILD   = python3 -m sphinx
+OPTS    =
+LATEST  = 2.0
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = ALOHA Documentation
-SOURCEDIR     = .
-BUILDDIR      = _build
-
-# Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(BUILD) -M help "$(SOURCE)" "$(OUT)" $(OPTS) $(O)
+	@echo "  multiversion to build documentation for all branches"
+
+multiversion: Makefile
+	sphinx-multiversion $(OPTS) "$(SOURCE)" "$(OUT)/html"
+	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=$(LATEST)/index.html\" /></head></html>" > $(OUT)/html/index.html
 
-.PHONY: help Makefile
+.PHONY: help Makefile multiversion
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS) $(O)
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
@@ -0,0 +1,26 @@
+{% extends "!page.html" %}
+{% block body %}
+{% if current_version and latest_version %}
+<p>
+  {% if current_version != latest_version %}
+  <div class="admonition warning">
+    <p class="admonition-title">Warning</p>
+    <p>
+      You are viewing the documentation for a version of the Interbotix ALOHA stack that is no longer supported.
+      Please upgrade to keep up to date with the latest features.
+      See the <a href="{{ vpathto(latest_version.name) }}">v{{latest_version.name | title }}</a> documentation for more information.
+    </p>
+  </div>
+  {% else %}
+  <div class="admonition note">
+    <p class="admonition-title">Warning</p>
+    <p>
+      The Interbotix ALOHA stack that has recently been updated to v2.0.
+      A full announcement is coming soon.
+    </p>
+  </div>
+  {% endif %}
+</p>
+{% endif %}
+{{ super() }}
+{% endblock %}%
diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html
@@ -0,0 +1,20 @@
+{%- if current_version %}
+
+<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"> Other Versions</span>
+    v{{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.branches %}
+    <dl>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">v{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+
+{%- endif %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -25,14 +25,15 @@
 extensions = [
     'sphinx_collapse',
     'sphinx_copybutton',
+    'sphinx_multiversion',
     'sphinx_tabs.tabs',
     'sphinx.ext.extlinks',
     'sphinx.ext.githubpages',
     'sphinx.ext.graphviz',
     'sphinx.ext.mathjax',
+    'sphinxcontrib.video',
     'sphinxcontrib.youtube',
     "sphinx.ext.autosectionlabel",
-    'sphinxcontrib.video',
 ]
 
 # True to prefix each section label with the name of the document it is in, followed by a colon.
@@ -56,6 +57,12 @@
     '_templates'
 ]
 
+# Whitelist pattern for branches (set to None to ignore all branches)
+# Set to a regex that will filter branches based on '$MAJOR.$MINOR' (e.g. '1.2')
+smv_branch_whitelist = r'^(\d+\.\d+)$'
+
+smv_latest_version = '2.0'
+
 # The suffix(es) of source filenames. You can specify multiple suffix as a list of string:
 source_suffix = '.rst'
 
@@ -198,5 +205,18 @@ def visit_reference(self, node: Element) -> None:
             self.body.append(('%s' + self.secnumber_suffix) %
                              '.'.join(map(str, node['secnumber'])))
 
+
+def smv_rewrite_configs(app, config):
+    if app.config.smv_current_version != '':
+        app.config.html_baseurl = app.config.html_baseurl + '/' + app.config.smv_current_version
+
+
+def github_link_rewrite_branch(app, pagename, templatename, context, doctree):
+    if app.config.smv_current_version != '':
+        context['github_version'] = app.config.smv_current_version + '/'
+
+
 def setup(app):
     app.set_translator('html', PatchedHTMLTranslator)
+    app.connect('config-inited', smv_rewrite_configs)
+    app.connect('html-page-context', github_link_rewrite_branch)
diff --git a/requirements.txt b/requirements.txt
@@ -1,9 +1,10 @@
-pip
 docutils==0.16
-sphinx==4.3.2
-sphinx-rtd-theme
-sphinxcontrib-youtube
-sphinxcontrib-video
-sphinx-copybutton
+pip
 sphinx-collapse
+sphinx-copybutton
+sphinx-rtd-theme
 sphinx-tabs
+sphinx-multiversion
+sphinx==4.3.2
+sphinxcontrib-video
+sphinxcontrib-youtube