samr-test-20241003

.github/workflows/docs.yml

@@ -0,0 +1,197 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'doc/**'
+
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'doc/**'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+
+  # These first jobs will run regardless of whether the PR branch is from ESCOMP/CTSM or a fork.
+
+  test-build-makefile:
+    if: ${{ always() }}
+    name: Test building documentation with makefile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs with makefile
+        run: |
+          make SPHINXOPTS="-W --keep-going" BUILDDIR=${PWD}/_build -C doc/ html
+
+  test-doc-builder:
+    if: ${{ always() }}
+    name: Test building documentation with doc-builder
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs with doc-builder
+        run: |
+          cd doc && ./build_docs -b ${PWD}/_build -c
+
+# The following jobs will only run if the PR branch is in ESCOMP/CTSM, not a fork.
+
+  cleanup:
+    permissions:
+      contents: write  #  for git push
+    name: Cleanup branch previews
+    runs-on: ubuntu-latest
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'gh-pages'
+          fetch-depth: 0
+          lfs: true
+          path: gh-pages
+      - name: Remove branch previews
+        run: |
+          pushd $GITHUB_WORKSPACE/gh-pages
+
+          if [[ -e "$GITHUB_WORKSPACE/gh-pages/branch" ]]; then
+            ls -la "$GITHUB_WORKSPACE/gh-pages/branch"
+
+            for name in `ls branch/`
+            do
+              if [[ -z "$(git show-ref --quiet ${name})" ]]
+              then
+                git rm -rf branch/${name}
+
+                echo "Removed $GITHUB_WORKSPACE/gh-pages/branch/${name}"
+              fi
+            done
+
+            git config user.name github-actions[bot]
+            git config user.email github-actions[bot]@users.noreply.github.com
+            git commit -m "Clean up branch previews"
+            git push
+          fi
+
+          echo "Done cleaning branches"
+  build-and-deploy:
+    permissions:
+      contents: write  #  for peaceiris/actions-gh-pages to push
+      pull-requests: write  #  to comment on pull requests
+    # needs: cleanup #
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install python 3.x
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+      # https://github.com/actions/cache/blob/main/examples.md#python---pip
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+      # Build documentation under ${PWD}/_build
+      - name: Build Sphinx docs
+        run: |
+          make SPHINXOPTS=-W --keep-going BUILDDIR=${PWD}/_build -C doc/ html
+      - name: Push PR preview
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          publish_branch: gh-pages-preview
+          publish_dir: './_build/html'
+          destination_dir: './branch/${{ github.event.pull_request.head.ref }}/html'
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+      - name: Comment about previewing documentation
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const havePosted = comments.map(x => x.user.login).some(x => x === "github-actions[bot]");
+
+            if (!havePosted) {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: 'You can preview documentation at https://escomp.github.io/ctsm/branch/${{ github.event.pull_request.head.ref }}/html/index.html'
+              })
+            }
+    #   - name: Push new docs
+    #     if: ${{ github.event_name == 'push' }}
+    #     uses: peaceiris/actions-gh-pages@v3
+    #     with:
+    #       github_token: ${{secrets.GITHUB_TOKEN}}
+    #       publish_dir: './_build/html'
+    #       destination_dir: './versions/master/html'
+    #       user_name: 'github-actions[bot]'
+    #       user_email: 'github-actions[bot]@users.noreply.github.com'
+

.gitmodules

@@ -123,8 +123,8 @@ fxDONOTUSEurl = https://github.com/NCAR/ParallelIO
 
 [submodule "doc-builder"]
 path = doc/doc-builder
-url = https://github.com/ESMCI/doc-builder
-fxtag = v1.0.8
+url = https://github.com/samsrabin/doc-builder
+fxtag = c51795f65d230803418c932bfd8639c85c33a19a
 fxrequired = ToplevelOptional
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/doc-builder

doc/requirements.txt

@@ -0,0 +1,4 @@
+esbonio == 0.16.4
+sphinx == 7.2.6
+sphinx-mdinclude == 0.6.2
+sphinx_rtd_theme == 2.0.0

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 %}

doc/source/conf.py

@@ -18,8 +18,6 @@
 #
 import os
 import sys
-# Note that we need a specific version of sphinx_rtd_theme. This can be obtained with:
-# pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
 import sphinx_rtd_theme
 # sys.path.insert(0, os.path.abspath('.'))
 
@@ -37,7 +35,9 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinx_mdinclude',
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -80,7 +80,7 @@
 #
 # 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.
@@ -109,9 +109,10 @@
 # names to html links. The current version can link to the current location (i.e., do
 # nothing). For the other version, we just add a place-holder; its name and value are
 # unimportant because these versions will get replaced dynamically.
-html_theme_options = {}
-html_theme_options['versions'] = {version: ''}
-html_theme_options['versions']['[placeholder]'] = ''
+### Sam Rabin 2024-10-02: Commented out to resolve "WARNING: unsupported theme option 'versions' given". Might break things!
+### html_theme_options = {}
+### html_theme_options['versions'] = {version: ''}
+### html_theme_options['versions']['[placeholder]'] = ''
 
 # 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,
@@ -178,7 +179,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
 
 numfig = True
 numfig_format = {'figure': 'Figure %s',
@@ -190,3 +191,17 @@
 
 def setup(app):
     app.add_css_file('css/custom.css')
+
+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