ESMCI · samsrabin · May 23, 2025 · May 21, 2025 · May 23, 2025 · May 23, 2025
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -1 +1,5 @@
 ce25647921a8f82c3b5009bdd07a620545b91a0c
+8762f2d8834a9ba391b73ca4ac36f3bb19b169ed
+04f3a94bdb9fc8c402286ebdc3ff9cb688c1e4b6
+81b7b35c4e07551459a98b7be17b6b6400d12e3a
+ac69349085bb8450d760cf33a5ee46701eadd4b9
diff --git a/__init__.py b/__init__.py
diff --git a/_static/css/custom.css b/_static/css/custom.css
@@ -0,0 +1,17 @@
+/* Make equation numbers float to the right */
+.eqno {
+    margin-left: 5px;
+    float: right;
+}
+/* Hide the link... */
+.math .headerlink {
+    display: none;
+    visibility: hidden;
+}
+/* ...unless the equation is hovered */
+.math:hover .headerlink {
+    display: inline-block;
+    visibility: visible;
+    /* Place link in margin and keep equation number aligned with boundary */
+    margin-right: -0.7em;
+}
diff --git a/_templates/footer.html b/_templates/footer.html
@@ -0,0 +1,5 @@
+{% extends "!footer.html" %}
+{% block extrafooter %}
+    {{ super() }}
+<script>var version_json_loc = "{{ pathto('../../versions.json', 1) }}";</script>
+{% endblock %}
diff --git a/_templates/landing.index.html b/_templates/landing.index.html
@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta http-equiv="refresh" content="0; url=PATH/TO/LANDING/PAGE.HTML" />
+  </head>
+</html>
diff --git a/_templates/versions.html b/_templates/versions.html
@@ -0,0 +1,26 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    Version: {{ current_version }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {% if languages|length >= 1 %}
+    <dl>
+      <dt>{{ _('Languages') }}</dt>
+        {% for the_language, url in languages %}
+          <dd><a href="{{ url }}/index.html">{{ the_language }}</a></dd>
+        {% endfor %}
+    </dl>
+    {% endif %}
+    {% if versions|length >= 1 %}
+    <dl>
+      <dt>{{ _('Versions') }}</dt>
+      {% for the_version, url in versions %}
+        <dd><a href="{{ url }}/index.html">{{ the_version }}</a></dd>
+      {% endfor %}
+    </dl>
+    {% endif %}
+    <br>
+    </dl>
+  </div>
+</div>
diff --git a/build_docs b/build_docs
@@ -8,7 +8,7 @@ This should be run from the directory that contains the Makefile for
 building the documentation.
 """
 
-from doc_builder import build_docs
+from doc_builder import build_docs  # pylint: disable=import-error
 
 if __name__ == "__main__":
     build_docs.main()
diff --git a/build_docs_to_publish b/build_docs_to_publish
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+
+"""
+Loop through all versions of the documentation, building each and moving it to a directory for
+publication.
+
+Adapted from https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-
+documentation-in-different-languages
+(last visited 2025-05-20)
+"""
+
+import sys
+import os
+import subprocess
+import argparse
+
+# pylint: disable=import-error,no-name-in-module
+from doc_builder.build_docs import (
+    main as build_docs,
+)
+from doc_builder.build_docs_shared_args import main as build_docs_shared_args
+from doc_builder.sys_utils import get_git_head_or_branch, check_permanent_file
+
+# Change to the parent director of doc-builder and add to Python path
+os.chdir(os.path.join(os.path.dirname(__file__), os.pardir))
+sys.path.insert(0, os.getcwd())
+
+# Import our definitions of each documentation version.
+# pylint: disable=wrong-import-position
+from version_list import (
+    LATEST_REF,
+    VERSION_LIST,
+)
+
+
+# Path to certain important files
+SOURCE = "source"
+VERSIONS_PY = os.path.join("version_list.py")
+MAKEFILE = "Makefile"
+
+
+def checkout_and_build(version, args):
+    """
+    Check out docs for a version and build
+    """
+
+    # Get the current branch, or SHA if detached HEAD
+    orig_ref = get_git_head_or_branch()
+
+    # Some files/directories/submodules must stay the same for all builds. We list these in
+    # the permanent_files list.
+    permanent_files = [VERSIONS_PY, "doc-builder", MAKEFILE]
+
+    # Check some things about "permanent" files before checkout
+    for filename in permanent_files:
+        check_permanent_file(filename)
+
+    # Check out the git reference of this version (branch name, tag, or commit SHA)
+    subprocess.check_output("git checkout " + version.ref, shell=True)
+
+    # Check out LATEST_REF version of permanent files
+    for filename in permanent_files:
+        subprocess.check_output(f"git checkout {LATEST_REF} -- {filename}", shell=True)
+
+    # Build the docs for this version
+    build_args = [
+        "-r",
+        args.repo_root,
+        "-v",
+        version.short_name,
+        "--version-display-name",
+        version.display_name,
+        "--versions",
+        "--site-root",
+        args.site_root,
+        "--clean",
+    ]
+    if args.build_with_docker:
+        build_args += ["-d"]
+    if args.conf_py_path:
+        build_args += ["--conf-py-path", args.conf_py_path]
+    if args.static_path:
+        build_args += ["--static-path", args.static_path]
+    if args.templates_path:
+        build_args += ["--templates-path", args.templates_path]
+    print(" ".join(build_args))
+    build_docs(build_args)
+
+    # Go back to original git status.
+    # 1. Get the current ref's version of doc-builder to avoid "would be overwritten by checkout"
+    #    errors.
+    subprocess.check_output("git submodule update --checkout doc-builder", shell=True)
+    # 2. Check out the original git ref (branch or commit SHA)
+    subprocess.check_output("git checkout " + orig_ref, shell=True)
+    # 3. Restore the current version's doc-builder
+    subprocess.check_output("git submodule update --checkout doc-builder", shell=True)
+
+
+def check_version_list():
+    """
+    Check version list for problems
+    """
+    has_default = False
+    for version in VERSION_LIST:
+        # Expect at most one version with landing_version True
+        if version.landing_version:
+            if has_default:
+                raise RuntimeError("Expected at most one version with landing_version True")
+            has_default = True
+
+
+def main():
+    """
+    Loop through all versions of the documentation, building each and moving it to a directory for
+    publication.
+    """
+    # Set up parser
+    parser = argparse.ArgumentParser()
+
+    # Arguments shared with build_docs
+    parser = build_docs_shared_args(parser)
+
+    # Custom arguments for build_docs_to_publish
+    parser.add_argument(
+        "--publish-dir",
+        default="_publish",
+        help="Where the docs should be moved after being built",
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Check version list for problems
+    check_version_list()
+
+    # Loop over all documentation versions
+    for version in VERSION_LIST:
+        # Build this version
+        checkout_and_build(version, args)
+
+        # Copy this version to the publication directory
+        src = os.path.join(args.repo_root, "versions", version.short_name, "html")
+        if version.landing_version:
+            dst = args.publish_dir
+        else:
+            dst = os.path.join(args.publish_dir, version.short_name)
+        os.makedirs(dst)
+        subprocess.check_output(f"mv '{src}'/* '{dst}'/", shell=True)
+
+
+if __name__ == "__main__":
+    main()