Severson-Group · AwesomeTornado · May 20, 2026
@@ -1,20 +1,60 @@
-# Minimal makefile for Sphinx documentation
+# Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= sphinx-multiversion
 SOURCEDIR     = source
 BUILDDIR      = build
+UNAME = "Windows_NT"
+ifeq ($(OS),Windows_NT)
+UNAME_AVAIL = "false"
+else
+UNAME_AVAIL = "true"
+endif
+
+ifeq ($(UNAME_AVAIL), "true")
+UNAME = $(shell uname -s)
+endif
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) --help
 
 .PHONY: help Makefile
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# Catch-all target: route all unknown targets to Sphinx
+# $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+ifeq ($(UNAME_AVAIL), "true")
+ifeq ($(UNAME), Darwin)
+	#We are on OSX
+	mkdir -p tmptmp
+	TMPDIR=$(CURDIR)/tmptmp $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+	rm -r tmptmp
+	cp ./index.html "$(BUILDDIR)/index.html"
+else
+	#We are on Linux
+	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+	cp ./index.html "$(BUILDDIR)/index.html"
+endif
+else
+	#We are on Windows_NT
+	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+	copy .\index.html "$(BUILDDIR)\index.html"
+endif
+
+
+local:
+	sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+
+# We are no longer using make functionality of sphinx-build
+# because sphinx-multiverison does not support it
+# therefore we must define make clean ourselves.
+clean:
+ifeq ($(OS),Windows_NT)
+	del /s "$(BUILDDIR)"
+else
+	rm -r "$(BUILDDIR)/"*
+endif
@@ -45,9 +45,9 @@ pip install -r requirements.txt
 
 ```
 make clean
-make html
+make local
 ```
 
-3. Browse local docs in your browser by opening: `build/html/index.html`
+3. Browse local docs in your browser by opening: `build/index.html`
 
 See [this discussion thread](https://github.com/Severson-Group/docs.amdc.dev/discussions/56) for more information on local development.
@@ -0,0 +1,3 @@
+<head>
+  <meta http-equiv='refresh' content='0; URL=https://docs.amdc.dev/main'>
+</head>
@@ -5,31 +5,39 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
+	set SPHINXBUILD=sphinx-multiversion
 )
 set SOURCEDIR=source
 set BUILDDIR=build
 
 if "%1" == "" goto help
+if "%1" == "clean" goto clean
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
+	echo.The 'sphinx-multiversion' command was not found. Make sure you have Sphinx
+	echo.and sphinx-multiversion installed, then set the SPHINXBUILD environment
+	echo.variable to point to the full path of the 'sphinx-build' executable.
+	echo.Alternatively you may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
 	echo.https://www.sphinx-doc.org/
+	echo.
+	echo.Sphinx-Multiversion can be installed with pip
+	echo.pip install sphinx-multiversion
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+%SPHINXBUILD% %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:clean
+del /s "$(BUILDDIR)"
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+%SPHINXBUILD% --help
 
 :end
 popd
@@ -2,10 +2,10 @@ sphinx>=6.0,<7
 furo>=2023.05
 myst_parser>=2.0
 sphinx_design>=0.4.1
-sphinx-last-updated-by-git>=0.3
 sphinx-copybutton>=0.4
 sphinx-sitemap>=2.2
 pygments>=2.10
 matplotlib>=3.7
 zipp>=3.1
-docutils<0.20,>=0.18.1
+docutils<0.20,>=0.18.1
+sphinx-multiversion>=0.2.4
@@ -0,0 +1,9 @@
+{% if versions %}
+<h4>{{ _('Versions') }}</h4>
+<ul style="display:flex; flex-direction:column-reverse">
+  {%- for item in versions.tags %}
+  <li style="flex: 0 0 auto;"><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+  <li><a href="{{ versions.branches[0].url }}">Latest</a></li>
+</ul>
+{% endif %}
@@ -31,10 +31,10 @@
 extensions = [
     'myst_parser',
     'sphinx_design',
-    'sphinx_last_updated_by_git',
     'sphinx_copybutton',
     'sphinx_sitemap',
-    'matplotlib.sphinxext.plot_directive'
+    'matplotlib.sphinxext.plot_directive',
+    'sphinx_multiversion'
 ]
 
 myst_enable_extensions = [
@@ -77,6 +77,30 @@
 
 html_extra_path = ['robots.txt']
 
+
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "versioning.html",
+        "sidebar/scroll-end.html",
+    ]
+}
+
+
+# Sphinx-multiversion configuration
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = r'^v\d\..*|main$'
+
+# Whitelist pattern for tags
+smv_tag_whitelist = r'^v\d\..*$'
+
+# Whitelist pattern for branches
+smv_branch_whitelist = r'^main$'
+
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -89,8 +113,9 @@
 ]
 
 
+
 # Matplotlib options
 plot_html_show_source_link = False
 plot_html_show_formats = False
 plot_formats = ['svg']
-plot_rcparams = {'font.size' : 12}
+plot_rcparams = {'font.size' : 12}
@@ -0,0 +1,31 @@
+# Developers
+
+This page serves as a guide to help people developing the documentation.
+
+## Versioning
+
+We use Sphinx-Multiversion to allow users to view historic revisions of our documentation.
+
+### Sphinx Multiversion Overview
+
+Sphinx has been configured to search for tags starting with `v#.` and add them to the version switcher at the bottom of the page. The version switcher has also been configured to put the branch named `main` at the very top, labled as `latest`.
+During the build process sphinx will go to the commits that the various tags are pointing to, build them, and put the results in seperate folders. Each folder is accessable online as a part of the url when visiting the docs. For example, `docs.amdc.dev/v1.0/index.html` points to the `v1.0` folder, while `docs.amdc.dev/v2.0/index.html` points to the `v2.0` folder.
+
+### Organization of Tags
+
+Each tag is a snapshot of the docs at one point in time, representing the most up to date documentation for the [AMDC-Firmware](https://github.com/Severson-Group/AMDC-Firmware) revision it is tagged as.
+Please note that the latest firmware release does not have its own tag! Instead, it is assumed that `main` contains the most up to date documentation for the current firmware revision.
+
+When releasing a new firmware version, the latest commit on `main` should be tagged as the firmware revision it was written for (the version prior to the one currently being released). This will give it an entry in the version selector. Now, any documentation for the new firmware release can now be merged in without removing access to previous documentation. The main branch remains the most up to date documentation, and now targets the new firmware version that was just released.
+
+```{NOTE}
+This project's policy is to only tag major and minor [AMDC-Firmware](https://github.com/Severson-Group/AMDC-Firmware) versions. Bug fix releases do not get their own tag in the docs. The tagging procedure is described in the [firmware release procedure](minor-or-major-release).
+```
+
+## Makefiles and Build scripts
+
+The Makefile is the most up to date method of building the documentation, and can be used by running `make clean` or `make html`.
+```{CAUTION}
+Sphinx-Multiversion does **not** take local changes into account when building the docs! Changes you want to view must be commited when testing the version switcher.
+```
+For building the documentation locally, `make local` can be used to only build the files on your computer, instead of building the entire version tree. This allows you to test changes without making commits.
@@ -71,13 +71,15 @@ Occasionally, a bug might need to be fixed in a previous release branch, but doe
 In this case, do not change `develop` -- simply fix the bug where it needs to be fixed.
 This is depicted in the above diagram as the `hotfix1` branch.
 
+(minor-or-major-release)=
 #### Minor or Major
 
 For a new minor or major release, a new release branch needs to be created.
 
-1. Create a new release branch from `develop` and call it `vA.B.x`
-2. Update GitHub's default repo branch to be the latest release branch which was just created
-3. Update the documentation website to reflect the minor or major (breaking) changes
+1. Tag the most recent commit to `main` on [docs.amdc.dev](https://github.com/Severson-Group/docs.amdc.dev) as the ***previous*** firmware release with `vA.B` formatting (see the [Developers guide](../../contribution/index.md))
+2. Create a new release branch from `develop` on AMDC-firmware and call it `vA.B.x`
+3. Update GitHub's default repo branch to be the latest release branch which was just created
+4. Update the documentation website to reflect the minor or major (breaking) changes
 
 ### Tag and Release
 
@@ -87,4 +89,4 @@ Users which checkout the release branch will have access to the code.
 To complete the release, git tag(s) need to be created and GitHub release(s) need to be created.
 
 1. Create git tag(s) pointing to the merge commit(s) on the release branch(es). If the new code was only merged to one release branch, only one tag will be created. However, if a bug fix was merged to multiple release branches, then the appropriate version number should be used to tag each merge commit.
-2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes per the changelog contents.
+2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes per the changelog contents.
@@ -51,6 +51,11 @@ AMDC Platform Documentation
    DAC <accessories/dac/index>
    accessories/test-board/index
 
+.. toctree::
+   :hidden:
+   :caption: Contribution
+
+   contribution/index
 
 Welcome to the AMDC Platform documentation.
 This is an ever-growing collection of knowledge about the AMDC.