Merge pull request #171 from altheaden/create-docs

Create documentation

.github/workflows/build_workflow.yml

@@ -111,3 +111,13 @@ jobs:
           pip check
           mache sync diags --help
           python conda/run_test.py
+
+      - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
+        name: Build Sphinx Docs
+        run: |
+          conda activate mache_dev
+          # sphinx-multiversion expects at least a "main" branch
+          git branch main || echo "branch main already exists."
+          cd docs
+          sphinx-multiversion . _build/html
+

.github/workflows/docs_workflow.yml

@@ -0,0 +1,93 @@
+name: CI/CD Release Workflow
+
+on:
+  push:
+    branches: [main]
+
+  release:
+    types: [published]
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Cache Conda
+        uses: actions/cache@v4
+        env:
+          # Increase this value to reset cache if deploy/conda-dev-spec.template has not changed in the workflow
+          CACHE_NUMBER: 0
+        with:
+          path: ~/conda_pkgs_dir
+          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
+            hashFiles('spec-file.txt') }}
+
+      - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
+        name: Set up Conda Environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: "mache_ci"
+          miniforge-version: latest
+          channels: conda-forge,e3sm/label/mache,defaults
+          channel-priority: strict
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+
+      - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
+        name: Install mache
+        run: |
+          git config --global url."https://github.com/".insteadOf "[email protected]:"
+          conda create -n mache_dev --file spec-file.txt \
+            python=${{ matrix.python-version }}
+          conda activate mache_dev
+          python -m pip install -e .
+
+      - name: Build Sphinx Docs
+        run: |
+          set -e
+          conda activate mache_dev
+          pip check
+          mache sync diags --help
+          cd docs
+          sphinx-multiversion . _build/html
+      - name: Copy Docs and Commit
+        run: |
+          set -e
+          conda activate mache_dev
+          pip check
+          mache sync diags --help
+          cd docs
+          # gh-pages branch must already exist
+          git clone https://github.com/E3SM-Project/mache.git --branch gh-pages --single-branch gh-pages
+          # 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 `main` branch automatically.
+          printf '<meta http-equiv="refresh" content="0; url=./main/index.html" />' > index.html
+          # Only replace `main` docs with latest changes. Docs for releases should be untouched.
+          rm -rf main
+          # 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]"
+          # The second command will fail if no changes were present, so we ignore it
+          git add .
+          git commit -m "Update documentation" -a || true
+      - name: Push Changes
+        uses: ad-m/github-push-action@master
+        with:
+          branch: gh-pages
+          directory: docs/gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          force: true
+

docs/.gitignore

@@ -0,0 +1,3 @@
+generated/
+.vscode
+.DS_Store

docs/Makefile

@@ -0,0 +1,28 @@
+# Minimal 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
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# raise warnings to errors
+html-strict:
+	@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf $(BUILDDIR) developers_guide/generated/ developers_guide/*/generated/
+

docs/_static/style.css

@@ -0,0 +1,4 @@
+.wy-nav-content {
+    max-width: 1200px !important;
+}
+

docs/_templates/layout.html

@@ -0,0 +1,5 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
+

docs/_templates/versions.html

@@ -0,0 +1,28 @@
+{%- if current_version %}
+<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"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}
+

docs/conf.py

@@ -0,0 +1,115 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+from datetime import date
+import sphinx_rtd_theme
+
+from sphinx.application import Sphinx
+from sphinx.transforms.post_transforms import SphinxPostTransform
+
+from mache.version import __version__
+
+# -- Project information -----------------------------------------------------
+
+project = "Mache"
+copyright = f"{date.today().year}, Energy Exascale Earth System Model Project"
+author = "E3SM Development Team"
+
+# 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.
+if 'DOCS_VERSION' in os.environ:
+    version = os.environ.get('DOCS_VERSION')
+    release = version
+else:
+    # The short X.Y.Z version.
+    version = __version__
+    # The full version, including alpha/beta/rc tags.
+    release = __version__
+
+master_doc = "index"
+language = "en"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_parser",
+    "sphinx_rtd_theme",
+    "sphinx_multiversion",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+]
+
+autosummary_generate = ['developers_guide/api.md']
+
+# Otherwise, the Return parameter list looks different from the Parameters list
+napoleon_use_rtype = False
+# Otherwise, the Attributes parameter list looks different from the Parameters
+# list
+napoleon_use_ivar = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+intersphinx_mapping = {
+    'geometric_features':
+        ('https://mpas-dev.github.io/geometric_features/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable', None),
+    'mpas_tools': ('https://mpas-dev.github.io/MPAS-Tools/stable', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'python': ('https://docs.python.org', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    'xarray': ('https://xarray.pydata.org/en/stable', None)
+}
+
+# -- MyST settings ---------------------------------------------------
+
+myst_enable_extensions = [
+    'colon_fence',
+    'deflist',
+    'dollarmath'
+]
+myst_number_code_blocks = ["typescript"]
+myst_heading_anchors = 2
+myst_footnote_transition = True
+myst_dmath_double_inline = True
+myst_enable_checkboxes = True
+
+# -- HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_title = ""
+
+# 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".
+html_static_path = ["_static"]
+
+html_sidebars = {
+    "**": [
+        "versions.html",
+    ],
+}
+
+smv_tag_whitelist = r"^\d+\.\d+.\d+$"  # Include tags like "tags/2.5.0"
+smv_branch_whitelist = "main"
+smv_remote_whitelist = r"^(origin|upstream)$"  # Use branches from origin
+

docs/developers_guide/adding_new_machine.md

@@ -0,0 +1,61 @@
+(dev-adding-new-machine)=
+
+# Adding a New Machine to Mache
+
+Adding an E3SM-known machine to mache requires adding a new config file, as 
+well as updating the list of machines in `discover.py`.
+
+:::{note}
+Only machines that are included in mache's 
+[machine config list](https://github.com/E3SM-Project/mache/blob/main/mache/cime_machine_config/config_machines.xml) 
+can be added to mache. This list is a *copy* of the 
+[E3SM cime machine config list](https://github.com/E3SM-Project/E3SM/blob/master/cime_config/machines/config_machines.xml) 
+which we try to keep up-to-date. If you wish to add a machine that is not 
+included in this list, you must contact the E3SM-Project developers to add your
+machine.
+:::
+
+(dev-new-config-file)=
+
+## Adding a new config file
+
+Adding a new config file is usually straightforward if you follow the format of
+an existing config file.
+
+(dev-discover-new-machine)=
+
+## Adding the new machine to `discover.py`
+
+You will need to amend the list of machine names in `discover.py` so that mache
+can identify the new machine via its hostname. This process is typically done 
+using a regular expression, which is often possible whenever the machine's 
+hostname follows a standardized format. For example, we can identify known 
+machines from hostnames with the following regular expressions:
+
+```python
+'^chr-\d{4}'  # Chrysalis compute nodes with hostnames chr-0000 to chr-9999
+'^compy'      # Compy nodes with hostname compy
+'^n\d{4}'     # Anvil nodes with hostnames n0000 to n9999
+```
+
+In some cases, the hostname assigned to a machine is too generic to 
+differentiate it from other machines. In these cases, we must identify the 
+machine by its environment variables. However, this is *not* the recommended 
+procedure and should only be done as a last resort. For example, we identify 
+`frontier` by its `LMOD_SYSTEM_NAME` environment variable:
+
+```python
+if machine is None and 'LMOD_SYSTEM_NAME' in os.environ:
+    hostname = os.environ['LMOD_SYSTEM_NAME']
+    if hostname == 'frontier':
+        # frontier's hostname is too generic to detect, so relying on
+        # LMOD_SYSTEM_NAME
+        machine = 'frontier'
+```
+
+:::{note}
+Identifying the machine by environment variables is **not recommended** unless
+absolutely necessary.
+:::
+
+