Switch to a custom version dropdown

.github/workflows/docs_workflow.yml

@@ -58,25 +58,34 @@ jobs:
           set -e
           cd conda_package/docs
           conda activate mpas_tools_dev
-          sphinx-multiversion . _build/html
+          DOCS_VERSION=${{ github.ref_name }} make versioned-html
       - name: Copy Docs and Commit
         run: |
           set -e
           cd conda_package/docs
           conda activate mpas_tools_dev
           # gh-pages branch must already exist
           git clone https://github.com/MPAS-Dev/MPAS-Tools.git --branch gh-pages --single-branch gh-pages
+
+          # Only replace docs in a directory with the destination branch name with latest changes. Docs for
+          # releases should be untouched.
+          rm -rf gh-pages/${{ github.ref_name }}
+
+          # don't clobber existing release versions (in case we retroactively fixed them)
+          cp -r _build/html/${{ github.ref_name }} gh-pages/
+
+          mkdir -p gh-pages/shared
+          cp shared/version-switcher.js gh-pages/shared/version-switcher.js
+
+          # Update the list of versions with all versions in the gh-pages directory.
+          python generate_versions_json.py
+
           # Make sure we're in the gh-pages directory.
           cd gh-pages
           # Create `.nojekyll` (if it doesn't already exist) for proper GH Pages configuration.
           touch .nojekyll
           # Add `index.html` to point to the `master` branch automatically.
           printf '<meta http-equiv="refresh" content="0; url=./master/index.html" />' > index.html
-          # Only replace docs in a directory with the destination branch name with latest changes. Docs for
-          # releases should be untouched.
-          rm -rf ${{ github.head_ref || github.ref_name }}
-          # don't clobber existing release versions (in case we retroactively fixed them)
-          cp -r -n ../_build/html/* .
           # Configure git using GitHub Actions credentials.
           git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"

conda_package/dev-spec.txt

@@ -35,6 +35,5 @@ setuptools
 
 # Documentation
 sphinx
-sphinx-multiversion
 mock
 sphinx_rtd_theme

conda_package/docs/Makefile

@@ -8,10 +8,35 @@ SPHINXPROJ    = mpas_tools
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+# Build into a versioned subdirectory
+versioned-html:
+	@echo "Building version: $(DOCS_VERSION)"
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/$(DOCS_VERSION)"
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(DOCS_VERSION)."
+	@echo "Setting up shared version switcher for local preview..."
+	mkdir -p _build/html/shared
+	cp shared/version-switcher.js _build/html/shared/version-switcher.js
+	python generate_versions_json.py --local
+
+# Override html target to include local setup
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+
+clean:
+	rm -rf generated
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean-versioned-html:
+	rm -rf $(BUILDDIR)/html/*
+	@echo "Cleaned versioned HTML builds."
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

conda_package/docs/_static/style.css

@@ -2,3 +2,28 @@
     max-width: 1200px !important;
 }
 
+#version-switcher select {
+    background-color: #2980b9;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    padding: 4px 30px 4px 10px;
+    font-size: 0.9em;
+    appearance: none; /* Remove default dropdown arrow */
+    background-image: url("data:image/svg+xml;charset=UTF-8,%3Csvg fill='white' height='10' viewBox='0 0 24 24' width='10' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M7 10l5 5 5-5z'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 10px center;
+    background-size: 12px;
+  }
+
+  #version-switcher select:focus {
+    outline: none;
+    box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.4);
+    background-color: #2c89c4; /* slightly lighter blue on focus */
+  }
+
+  /* Selected item in the dropdown menu */
+  #version-switcher option:checked {
+    background-color: #dddddd;  /* for selected */
+    color: black;
+  }

conda_package/docs/_templates/layout.html

@@ -1,5 +1,27 @@
 {% extends "!layout.html" %}
+
 {% block extrahead %}
     <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
 {% endblock %}
 
+{% block footer %}
+  {{ super() }}
+
+  <!-- Meta tags for JS to use -->
+  <meta name="doc-version" content="{{ current_version }}">
+  <meta name="doc-site-root" content="{{ pathto('', 1) }}">
+
+  <!-- Create version switcher container -->
+  <script>
+    const sidebar = document.querySelector('.wy-side-nav-search');
+    if (sidebar) {
+      const versionDiv = document.createElement('div');
+      versionDiv.id = 'version-switcher';
+      versionDiv.style.marginTop = '1em';
+      sidebar.appendChild(versionDiv);
+    }
+  </script>
+
+  <!-- Load version-switcher.js using the correct relative path -->
+  <script src="{{ pathto('../shared/version-switcher.js', 1) }}"></script>
+{% endblock %}

conda_package/docs/building_docs.rst

@@ -9,10 +9,21 @@ To make a local test build of the documentation, it is easiest to follow the
 ``mpas_tools`` package.  The development environment includes the packages
 needed to build the documentation. Simply run:
 
-code-block::
+.. code-block:: bash
 
-  export DOCS_VERSION="test"
   cd conda_package/docs
-  make html
+  DOCS_VERSION=master make versioned-html
 
-Then, you can view the documentation by opening ``_build/html/index.html``.
+****************************
+Previewing the Documentation
+****************************
+
+To preview the documentation locally, open the ``index.html`` file in the
+``_build/html/master`` directory with your browser or try:
+
+.. code-block:: bash
+
+  cd _build/html
+  python -m http.server 8000
+
+Then, open http://0.0.0.0:8000/master/ in your browser.

conda_package/docs/conf.py

@@ -27,7 +27,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx_rtd_theme',
-              'sphinx_multiversion',
               'sphinx.ext.autodoc',
               'sphinx.ext.autosummary',
               'sphinx.ext.intersphinx',
@@ -191,14 +190,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-html_sidebars = {
-    "**": [
-        "versions.html",
-    ],
+html_context = {
+    "current_version": os.getenv("DOCS_VERSION", "master"),
 }
-
-# -- Options sphinx-multiversion -------------------------------------------
-# Include tags like "tags/1.0.0" -- 0.0.1, 0.0.10 don't build
-smv_tag_whitelist = r'^(?!(0.0.1|0.0.10))\d+\.\d+.\d+$'
-smv_branch_whitelist = 'master'
-smv_remote_whitelist = 'origin'

conda_package/docs/generate_versions_json.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+import argparse
+import json
+import os
+
+# Mode: local or production
+parser = argparse.ArgumentParser(
+    description='Generate versions.json for MPAS-Tools documentation.')
+parser.add_argument(
+    '--local',
+    action='store_true',
+    help='Generate versions.json for local build.'
+)
+args = parser.parse_args()
+local = args.local
+base_dir = '_build/html' if local else 'gh-pages'
+shared_dir = os.path.join(base_dir, 'shared')
+
+entries = []
+
+if not os.path.exists(base_dir) or not os.listdir(base_dir):
+    raise FileNotFoundError(
+        f"Base directory '{base_dir}' does not exist or is empty.")
+
+versions = sorted(os.listdir(base_dir), reverse=True)
+if 'master' in versions:
+    versions.insert(0, versions.pop(versions.index('master')))
+
+for name in versions:
+    path = os.path.join(base_dir, name)
+    if os.path.isdir(path) and name not in ('shared', '.git'):
+        entries.append({
+            'version': name,
+            'url': f'../{name}/' if local else f'/MPAS-Tools/{name}/'
+        })
+
+os.makedirs(shared_dir, exist_ok=True)
+with open(os.path.join(shared_dir, 'versions.json'), 'w') as f:
+    json.dump(entries, f, indent=2)

conda_package/docs/index.rst

@@ -33,7 +33,13 @@ analyzing simulations, and in other MPAS-related workflows.
 
    vector
 
+.. toctree::
+   :caption: Visualization
+   :maxdepth: 2
+
    visualization
+   mpas_to_xdmf
+   paraview_extractor
 
 .. toctree::
    :caption: Landice Tools

conda_package/docs/making_changes.rst

@@ -162,20 +162,3 @@ needs to match:
 
   {% set name = "mpas_tools" %}
   {% set version = "0.6.0" %}
-
-Third, Add the new version to the :ref:`versions` in the documentation.
-
-.. code-block::
-
-    `v0.6.0`_         `0.6.0`_
-    ================ ===============
-
-    ...
-
-    .. _`v0.6.0`: ../0.6.0/index.html
-    .. _`0.6.0`: https://github.com/MPAS-Dev/MPAS-Analysis/tree/0.6.0
-
-
-The new links won't be valid until a new release is made and Azure Pipelines
-has generated the associated documentation.  Eventually, it should be possible
-to do this automatically but that has not yet been implemented.

conda_package/docs/mpas_to_xdmf.rst

@@ -139,10 +139,13 @@ ParaView for visualization. Follow these steps:
 
 2. **Choose the Correct Reader**: When opening the ``.xdmf`` file, ParaView
    will prompt you to select one of three readers:
+
    - **Xdmf3 Reader S**: This reader is optimized for static datasets without
      time information. It is not suitable for time-varying MPAS data.
+
    - **Xdmf3 Reader T**: This reader is designed for time-varying datasets and
      is the preferred choice for MPAS data converted with this tool.
+
    - **XDMF Reader**: This is an older reader that may not fully support modern
      XDMF features and should generally be avoided.
 

conda_package/docs/paraview_extractor.rst

@@ -64,6 +64,8 @@ additional storage space.
 Since the extractor is fairly complex with a lot of possible use cases, we will
 describe its functionality in several examples.
 
+.. _extract_temperature:
+
 Extracting a Temperature Time-series
 ------------------------------------
 
@@ -273,7 +275,7 @@ The resulting fields are named:
     timeDaily_avg_layerThickness_maxLevelCell
 
 Indexing Time
-------------------------------------
+-------------
 
 Time can also be indexed like the other dimensions, but it is not passed to the
 ``dimension_list`` argument but instead to the ``time`` argument.  The time
@@ -453,7 +455,7 @@ Here is the bottom temperature in such a plot:
    :align: center
 
 Extracting a Region
-------------------------------------
+-------------------
 
 Some simulations are focused on a small region, even though the entire globe is
 included in the mesh.  For such situations, we provide a way to extract a
@@ -492,6 +494,8 @@ In this example, we extract sea surface temperature only in the Southern Ocean:
    :width: 500 px
    :align: center
 
+.. _paraview_macros:
+
 ParaView Macros
 ---------------
 

conda_package/docs/shared/version-switcher.js

@@ -0,0 +1,42 @@
+(async function () {
+    const container = document.getElementById("version-switcher");
+    if (!container) return;
+
+    const metaVersion = document.querySelector('meta[name="doc-version"]');
+    const currentVersion = metaVersion ? metaVersion.content : "unknown";
+    console.log("Stored current version:", currentVersion);
+
+    async function fetchVersions() {
+      try {
+        const res = await fetch("/shared/versions.json");
+        if (!res.ok) throw new Error();
+        return await res.json();
+      } catch {
+        const res = await fetch("../shared/versions.json");
+        return await res.json();
+      }
+    }
+
+    const versions = await fetchVersions();
+
+    const select = document.createElement("select");
+    select.style.marginLeft = "1em";
+    select.onchange = () => {
+      window.location.href = select.value;
+    };
+
+    versions.forEach(({ version, url }) => {
+      const option = document.createElement("option");
+      option.value = url;
+      option.textContent = version;
+      if (url.includes(`/${currentVersion}/`)) {
+        option.selected = true;
+      }
+      select.appendChild(option);
+    });
+
+    const label = document.createElement("label");
+    label.textContent = "Version: ";
+    label.appendChild(select);
+    container.appendChild(label);
+  })();