Merge pull request #4613 from ESMCI/fix_docs_version

Updates documentation versioning
ESMCI · Apr 24, 2024 · a3abfd9 · a3abfd9
2 parents 591f4e5 + 5e31e25
commit a3abfd9
Show file tree

Hide file tree

Showing 6 changed files with 91 additions and 55 deletions.
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,5 +1,4 @@
 sphinx
 sphinxcontrib-programoutput
 sphinx-rtd-theme
-# git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
 evv4esm
diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css
diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js
diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html
diff --git a/doc/source/_templates/versions.html b/doc/source/_templates/versions.html
@@ -0,0 +1,64 @@
+{% if READTHEDOCS or display_lower_left %}
+{# Add rst-badge after rst-versions for small badge style. #}
+  <script type="text/javascript">
+    let baseUriRegex = /(.*\/cime)\/.*/g;
+    let parsedUri = baseUriRegex.exec(document.baseURI);
+
+    if (parsedUri != null && parsedUri.length == 2) {
+      let baseUri = parsedUri[1];
+
+      $.get(`${baseUri}/versions/versions.json`, function(data) {
+        let versionElement = $("#versions");
+
+        Object.keys(data).forEach(function(key) {
+          let value = data[key];
+
+          let item = `<dd><a href="${baseUri}/versions/${key}/html/">${value}</a></dd>`
+
+          versionElement.append(item);
+        });
+      });
+    }
+  </script>
+  <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"> Read the Docs</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      {% if languages|length >= 1 %}
+      <dl>
+        <dt>{{ _('Languages') }}</dt>
+        {% for slug, url in languages %}
+          {% if slug == current_language %} <strong> {% endif %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+          {% if slug == current_language %} </strong> {% endif %}
+        {% endfor %}
+      </dl>
+      {% endif %}
+      <dl id="versions">
+        <dt>Versions</dt>
+      </dl>
+      {% if downloads|length >= 1 %}
+      <dl>
+        <dt>{{ _('Downloads') }}</dt>
+        {% for type, url in downloads %}
+          <dd><a href="{{ url }}">{{ type }}</a></dd>
+        {% endfor %}
+      </dl>
+      {% endif %}
+      {% if READTHEDOCS %}
+      <dl>
+        <dt>{{ _('On Read the Docs') }}</dt>
+          <dd>
+            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
+          </dd>
+          <dd>
+            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
+          </dd>
+      </dl>
+      {% endif %}
+    </div>
+  </div>
+{% endif %}
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -62,25 +62,25 @@
 master_doc = "index"
 
 # General information about the project.
-project = u"CIME"
-copyright = u"2017, U.S. National Science Foundation and U.S. Department of Energy"
-author = u"Staff of the NSF/CESM and DOE/E3SM projects"
+project = "CIME"
+copyright = "2017, U.S. National Science Foundation and U.S. Department of Energy"
+author = "Staff of the NSF/CESM and DOE/E3SM projects"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u"master"
+version = "master"
 # The full version, including alpha/beta/rc tags.
-release = u"master"
+release = "master"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -156,8 +156,8 @@
     (
         master_doc,
         "on.tex",
-        u"on Documentation",
-        u"Staff of the NSF/CESM and DOE/E3SM projects",
+        "on Documentation",
+        "Staff of the NSF/CESM and DOE/E3SM projects",
         "manual",
     ),
 ]
@@ -167,7 +167,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "on", u"on Documentation", [author], 1)]
+man_pages = [(master_doc, "on", "on Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -179,7 +179,7 @@
     (
         master_doc,
         "on",
-        u"on Documentation",
+        "on Documentation",
         author,
         "on",
         "One line description of project.",
@@ -192,8 +192,22 @@
 pdf_documents = [
     (
         master_doc,
-        u"CIME_Users_Guide",
-        u"CIME Users Guide (PDF)",
-        u"Staff of the NSF/CESM and DOE/E3SM projects",
+        "CIME_Users_Guide",
+        "CIME Users Guide (PDF)",
+        "Staff of the NSF/CESM and DOE/E3SM projects",
     ),
 ]
+
+try:
+    html_context
+except NameError:
+    html_context = dict()
+
+html_context["display_lower_left"] = True
+
+html_context["current_language"] = language
+
+current_version = "master"
+
+html_context["current_version"] = current_version
+html_context["version"] = current_version