Add versioning to docs

.github/workflows/build_and_test.yml

@@ -14,6 +14,8 @@ jobs:
     steps:
       - name: Check out repository code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Python
         uses: actions/setup-python@v5

Makefile

@@ -2,17 +2,25 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -Dversion=$(shell git tag --sort=committerdate | tail -1)
-SPHINXBUILD   = sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = docs
+SPHINXOPTS    			= -Dversion=$(shell git tag --sort=committerdate | tail -1)
+SPHINXBUILD   			= sphinx-build
+SPHINXBUILDMULTIVERSION = sphinx-multiversion
+SOURCEDIR     			= source
+BUILDDIR      			= docs
+BUILDDIRHTML			= $(BUILDDIR)/html
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
 
 .PHONY: help Makefile
 
+# make html: Order of inputs for building with sphinx-multiversion is different
+# than using sphinx-build; explicitly define `make html` target here
+html: Makefile
+	@$(SPHINXBUILDMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIRHTML)" $(SPHINXOPTS) $(O)
+	cp source/_templates/redirect.html "$(BUILDDIRHTML)/index.html"
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

Pipfile

@@ -11,3 +11,6 @@ make = "*"
 breathe = "*"
 jinja2 = "*"
 sphinx-csharp = {git = "https://github.com/rogerbarton/sphinx-csharp.git", ref = "master"}
+sphinx-multiversion = "*"
+
+[dev-packages]

README.rst

@@ -24,7 +24,10 @@ Create a virtual environment with pipenv (will use the Pipfile for installing th
 
    pipenv install
 
-Then you can build the documentation.
+Then you can build the documentation. Note that ``make html`` will call
+``sphinx-multiversion`` and will automatically build all tags and branches as
+defined in the conf.py file. For more details, see the section on
+``sphinx-multiversion`` below.
 
 .. code:: shell
 
@@ -46,7 +49,10 @@ and then you can use ``make`` the usual way.
    make latexpdf # for latex (will require latexpdf installed)
    make          # list all the available output format
 
-All the outputs will be in the docs folder (for html: docs/html).
+All the outputs will be in the docs folder (for html: docs/html). Note that
+there will be a folder for every tag or branch that is being built by
+``sphinx-multiversion``, as well as a redirect page at the root to automatically
+redirect to the main branch build.
 
 without pipenv/virtualenv
 -------------------------
@@ -67,3 +73,34 @@ After installing the requirements you can run:
    make latex    # for latex
    make latexpdf # for latex (will require latexpdf installed)
    make          # list all the available output format
+
+Sphinx Multiversion Extension
+===============================
+
+The ``sphinx-multiversion`` extension is used to automate the build for all tags
+and the main branch of these docs. This allows a dropdown menu to be placed in
+the left sidebar where the user can choose which version of the docs they want
+to browse. This dropdown menu is governed by the
+'source/_templates/versioning.html' file, and can be modified via HTML/CSS to
+any theme or visualization.
+
+Note that this extension is not building the uncommitted files in the current
+working directory; it is building the files that have been committed to the
+branch locally. This means that **you must commit all files locally before
+building if you want to preview the pages**. Additionally, if your local
+branches (i.e., main) are not up to date, your local preview may not reflect
+the most recent changes to the repo.
+
+It is also important to note that if you
+are working in a feature branch, it is not automatically pulled into the build
+due to the branch whitelist found in the conf.py file. To test changes
+that have been committed locally, add the current branch to the
+``smv_branch_whitelist`` regular expression. For example, if the current working
+branch is ``issue-XX``, then the new regular expression can be modified to be
+"r'^(main|issue-XX)$'". Be sure to revert the changes to the conf.py file before
+merging to main, otherwise the feature branch will be built in the online
+version.
+
+For more information on the extension, and the different configuration options,
+check out their `documentation site
+<https://sphinx-contrib.github.io/multiversion/main/index.html>`__.

source/_templates/redirect.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to master branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="https://open-ephys.github.io/ONI/main/index.html">
+  </head>
+</html>

source/_templates/versioning.html

@@ -0,0 +1,23 @@
+<div id="version_container">
+    <span style="vertical-align: middle">{{ _('Version') }}</span>
+    <select
+      style="vertical-align: middle; margin-left: 5px"
+      onchange="window.location.href=this.value"
+      id="version_dropdown_menu"
+    >
+      {% if versions %}
+      {%- for item in versions %}
+      <option value="{{ item.url }}">{{ item.name }}</a></li>
+      {%- endfor %}
+      {% endif %}
+    </select>
+ </div>
+ <script>
+    var dropdown = document.getElementById('version_dropdown_menu');
+
+    for (var i = 0; i < dropdown.options.length; i++) {
+        if (window.location.pathname.includes(dropdown.options[i].label)) {
+            dropdown.options[i].selected = true;
+        }
+    }
+  </script>

source/conf.py

@@ -45,6 +45,7 @@
     'sphinx.ext.githubpages',
     'breathe',
     'sphinx_csharp',
+    'sphinx_multiversion'
 ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -106,8 +107,8 @@
 html_style = "_static/theme_overrides.css"
 
 html_sidebars = {
-    'index': ['search-field.html'],
-    "**": ["sidebar-nav-bs.html"]
+    'index': ['versioning.html','search-field.html'],
+    "**": ['versioning.html',"sidebar-nav-bs.html"]
 }
 
 # Custom sidebar templates, must be a dictionary that maps document names
@@ -240,3 +241,9 @@
 
 # Option for linkcheck
 linkcheck_anchors = False
+
+# Options for sphinx-multiversion
+smv_branch_whitelist = r'^main$'
+smv_tag_whitelist = r'^v\d+\.\d+$'
+smv_remote_whitelist = r'^(origin)$'
+smv_released_pattern = r'^tags/.*$'