-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #171 from altheaden/create-docs
Create documentation
- Loading branch information
Showing
14 changed files
with
765 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
generated/ | ||
.vscode | ||
.DS_Store |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/ | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
.wy-nav-content { | ||
max-width: 1200px !important; | ||
} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{% extends "!layout.html" %} | ||
{% block extrahead %} | ||
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css"> | ||
{% endblock %} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 %} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
::: | ||
|
||
|
Oops, something went wrong.