Skip to content

Commit 6a8e026

Browse files
xylarxylar
authored
Merge pull request #129 from xylar/add-docs-workflow
Add docs workflow
2 parents b234753 + 5d9d476 commit 6a8e026

File tree

14 files changed

+492
-8
lines changed

14 files changed

+492
-8
lines changed

‎.github/workflows/build_workflow.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: CI/CD Build Workflow
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
pull_request:
8+
branches: [main]
9+
10+
workflow_dispatch:
11+
12+
env:
13+
CANCEL_OTHERS: false
14+
PATHS_IGNORE: '["**/README.md", "**/docs/**"]'
15+
16+
jobs:
17+
build:
18+
name: test E3SM-Unified - python ${{ matrix.python-version }} - mpi ${{ matrix.mpi }}
19+
runs-on: ubuntu-latest
20+
timeout-minutes: 20
21+
defaults:
22+
run:
23+
shell: bash -l {0}
24+
strategy:
25+
matrix:
26+
python-version: ["3.9", "3.10"]
27+
mpi: ["hpc", "nompi", "mpich", "openmpi"]
28+
fail-fast: false
29+
steps:
30+
- uses: actions/checkout@v4
31+
32+
- name: Create Build Environment
33+
uses: mamba-org/setup-micromamba@v2
34+
with:
35+
environment-name: e3sm_unified_dev
36+
init-shell: bash
37+
condarc: |
38+
channel_priority: strict
39+
channels:
40+
- conda-forge
41+
create-args: >-
42+
python=${{ matrix.python-version }}
43+
44+
- name: Finalize Build Environment
45+
run: |
46+
conda install -y conda conda-build
47+
conda build -m "recipes/e3sm-unified/configs/mpi_${{ matrix.mpi }}_python${{ matrix.python-version }}.yaml" "recipes/e3sm-unified"
48+
49+
- name: Install E3SM-Unified
50+
run: |
51+
conda install -y -c ${CONDA_PREFIX}/conda-bld/ e3sm-unified
52+
conda install -y --file dev-spec.txt
53+
54+
- name: Build Sphinx Docs
55+
run: |
56+
cd docs
57+
DOCS_VERSION=test make versioned-html
58+
condarc: |
59+
channel_priority: strict
60+
channels:
61+
- conda-forge
62+
create-args: >-
63+
python=${{ matrix.python-version }}

‎.github/workflows/docs_workflow.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: CI/CD Release Workflow
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
release:
8+
types: [published]
9+
10+
env:
11+
PYTHON_VERSION: "3.10"
12+
13+
jobs:
14+
publish-docs:
15+
runs-on: ubuntu-latest
16+
defaults:
17+
run:
18+
shell: bash -l {0}
19+
timeout-minutes: 20
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
persist-credentials: false
24+
fetch-depth: 0
25+
26+
- name: Set up Conda Environment
27+
uses: mamba-org/setup-micromamba@v2
28+
with:
29+
environment-name: e3sm_unified_dev
30+
init-shell: bash
31+
condarc: |
32+
channel_priority: strict
33+
channels:
34+
- conda-forge
35+
create-args: >-
36+
python=${{ env.PYTHON_VERSION }}
37+
38+
- name: Install e3sm-unified
39+
run: |
40+
git config --global url."https://github.com/".insteadOf "[email protected]:"
41+
conda install -y --file dev-spec.txt
42+
43+
- name: Build Sphinx Docs
44+
run: |
45+
set -e
46+
cd docs
47+
DOCS_VERSION=${{ github.ref_name }} make versioned-html
48+
- name: Copy Docs and Commit
49+
run: |
50+
set -e
51+
cd conda_package/docs
52+
# gh-pages branch must already exist
53+
git clone https://github.com/E3SM-Project/e3sm-unified.git --branch gh-pages --single-branch gh-pages
54+
55+
# Only replace docs in a directory with the destination branch name with latest changes. Docs for
56+
# releases should be untouched.
57+
rm -rf gh-pages/${{ github.ref_name }}
58+
59+
# don't clobber existing release versions (in case we retroactively fixed them)
60+
cp -r _build/html/${{ github.ref_name }} gh-pages/
61+
62+
mkdir -p gh-pages/shared
63+
cp shared/version-switcher.js gh-pages/shared/version-switcher.js
64+
65+
# Update the list of versions with all versions in the gh-pages directory.
66+
python generate_versions_json.py
67+
68+
# Make sure we're in the gh-pages directory.
69+
cd gh-pages
70+
# Create `.nojekyll` (if it doesn't already exist) for proper GH Pages configuration.
71+
touch .nojekyll
72+
# Add `index.html` to point to the `master` branch automatically.
73+
printf '<meta http-equiv="refresh" content="0; url=./master/index.html" />' > index.html
74+
# Configure git using GitHub Actions credentials.
75+
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
76+
git config --local user.name "github-actions[bot]"
77+
# The second command will fail if no changes were present, so we ignore it
78+
git add .
79+
git commit -m "Update documentation" -a || true
80+
- name: Push Changes
81+
uses: ad-m/github-push-action@master
82+
with:
83+
branch: gh-pages
84+
directory: conda_package/docs/gh-pages
85+
github_token: ${{ secrets.GITHUB_TOKEN }}
86+
force: true

‎README.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
11
# E3SM-Unified
22

3-
![E3SM-Unified](e3sm_unified_logo_200.png)
3+
![E3SM-Unified](docs/logo/e3sm_unified_logo_200.png)
44

55
A metapackage for a unified
66
[conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
7-
for analysis an other post-processing of results from Energy Exascale Earth
8-
System Model (E3SM) simulations.
7+
for analysis and other pre- and post-processing for the Energy Exascale Earth
8+
System Model (E3SM).
99

1010
E3SM-Unified currently supports Linux and OSX, and python >=3.9,<3.11.
1111
Support for Windows is not planned.
1212

1313
To create a new conda environment on a laptop or workstation (or on
1414
HPC that is not already supported by the E3SM team), first install
15-
[Miniforge3](https://github.com/conda-forge/miniforge#miniforge3). Then,
16-
create the E3SM-Unified environment (with MPI support from the `mpich` package
17-
in this example), use:
15+
[Miniforge3](https://github.com/conda-forge/miniforge?tab=readme-ov-file#requirements-and-installers).
16+
Then, create the E3SM-Unified environment (with MPI support from the `mpich`
17+
package in this example), use:
1818
```bash
19-
conda create -n e3sm-unified -c conda-forge -c defaults -c e3sm \
20-
python=3.10 "e3sm-unified=*=mpi_mpich_*"
19+
conda create -n e3sm-unified -c conda-forge python=3.10 "e3sm-unified=*=mpi_mpich_*"
2120
conda activate e3sm-unified
2221
```
2322
Each time you want to use the environment in the future, again run:

‎dev-speck.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Documentation
2+
sphinx >=7.0.0
3+
sphinx_rtd_theme
4+
myst-parser

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
generated/
2+
.vscode
3+
.DS_Store

‎docs/Makefile‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Build into a versioned subdirectory
12+
versioned-html:
13+
@echo "Building version: $(DOCS_VERSION)"
14+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/$(DOCS_VERSION)"
15+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(DOCS_VERSION)."
16+
@echo "Setting up shared version switcher for local preview..."
17+
mkdir -p _build/html/shared
18+
cp shared/version-switcher.js _build/html/shared/version-switcher.js
19+
python generate_versions_json.py --local
20+
21+
# Override html target to include local setup
22+
html:
23+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
24+
@echo
25+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
26+
27+
# Put it first so that "make" without argument is like "make help".
28+
help:
29+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
30+
31+
.PHONY: help Makefile
32+
33+
# Catch-all target: route all unknown targets to Sphinx using the new
34+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
35+
%: Makefile
36+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
37+
38+
# raise warnings to errors
39+
html-strict:
40+
@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
41+
42+
clean:
43+
rm -rf $(BUILDDIR) developers_guide/generated/ developers_guide/*/generated/
44+
45+
clean-versioned-html:
46+
rm -rf $(BUILDDIR)/html/*
47+
@echo "Cleaned versioned HTML builds."
48+

‎docs/_static/style.css‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.wy-nav-content {
2+
max-width: 1200px !important;
3+
}
4+
5+
#version-switcher select {
6+
background-color: #2980b9;
7+
color: white;
8+
border: none;
9+
border-radius: 4px;
10+
padding: 4px 30px 4px 10px;
11+
font-size: 0.9em;
12+
appearance: none; /* Remove default dropdown arrow */
13+
background-image: url("data:image/svg+xml;charset=UTF-8,%3Csvg fill='white' height='10' viewBox='0 0 24 24' width='10' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M7 10l5 5 5-5z'/%3E%3C/svg%3E");
14+
background-repeat: no-repeat;
15+
background-position: right 10px center;
16+
background-size: 12px;
17+
}
18+
19+
#version-switcher select:focus {
20+
outline: none;
21+
box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.4);
22+
background-color: #2c89c4; /* slightly lighter blue on focus */
23+
}
24+
25+
/* Selected item in the dropdown menu */
26+
#version-switcher option:checked {
27+
background-color: #dddddd; /* for selected */
28+
color: black;
29+
}
30+

‎docs/_templates/layout.html‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{% extends "!layout.html" %}
2+
{% block extrahead %}
3+
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
4+
{% endblock %}
5+
6+
{% block footer %}
7+
{{ super() }}
8+
9+
<!-- Meta tags for JS to use -->
10+
<meta name="doc-version" content="{{ current_version }}">
11+
<meta name="doc-site-root" content="{{ pathto('', 1) }}">
12+
13+
<!-- Create version switcher container -->
14+
<script>
15+
const sidebar = document.querySelector('.wy-side-nav-search');
16+
if (sidebar) {
17+
const versionDiv = document.createElement('div');
18+
versionDiv.id = 'version-switcher';
19+
versionDiv.style.marginTop = '1em';
20+
sidebar.appendChild(versionDiv);
21+
}
22+
</script>
23+
24+
<!-- Load version-switcher.js using the correct relative path -->
25+
<script src="{{ pathto('../shared/version-switcher.js', 1) }}"></script>
26+
{% endblock %}
27+

‎docs/conf.py‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
import os
8+
from datetime import date
9+
10+
# -- Project information -----------------------------------------------------
11+
12+
project = "E3SM-Unified"
13+
copyright = f"{date.today().year}, Energy Exascale Earth System Model Project"
14+
author = "E3SM Development Team"
15+
16+
# The version info for the project you're documenting, acts as replacement for
17+
# |version| and |release|, also used in various other places throughout the
18+
# built documents.
19+
if 'DOCS_VERSION' in os.environ:
20+
version = os.environ.get('DOCS_VERSION')
21+
release = version
22+
else:
23+
version = "test"
24+
release = version
25+
26+
master_doc = "index"
27+
language = "en"
28+
29+
# -- General configuration ---------------------------------------------------
30+
31+
# Add any Sphinx extension module names here, as strings. They can be
32+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33+
# ones.
34+
extensions = [
35+
"myst_parser",
36+
"sphinx_rtd_theme",
37+
"sphinx.ext.autodoc",
38+
"sphinx.ext.autosummary",
39+
"sphinx.ext.intersphinx",
40+
"sphinx.ext.viewcode",
41+
"sphinx.ext.mathjax",
42+
"sphinx.ext.napoleon",
43+
]
44+
45+
autosummary_generate = ['developers_guide/api.md']
46+
47+
# Otherwise, the Return parameter list looks different from the Parameters list
48+
napoleon_use_rtype = False
49+
# Otherwise, the Attributes parameter list looks different from the Parameters
50+
# list
51+
napoleon_use_ivar = True
52+
53+
# Add any paths that contain templates here, relative to this directory.
54+
templates_path = ["_templates"]
55+
56+
# List of patterns, relative to source directory, that match files and
57+
# directories to ignore when looking for source files.
58+
# This pattern also affects html_static_path and html_extra_path.
59+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
60+
61+
intersphinx_mapping = {
62+
'mache': ('https://docs.e3sm.org/mache/main', None),
63+
'matplotlib': ('https://matplotlib.org/stable', None),
64+
'numpy': ('https://numpy.org/doc/stable', None),
65+
'python': ('https://docs.python.org', None),
66+
'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
67+
"sphinx": ("https://www.sphinx-doc.org/en/master", None),
68+
'xarray': ('https://xarray.pydata.org/en/stable', None)
69+
}
70+
71+
# -- MyST settings ---------------------------------------------------
72+
73+
myst_enable_extensions = [
74+
'colon_fence',
75+
'deflist',
76+
'dollarmath'
77+
]
78+
myst_number_code_blocks = ["typescript"]
79+
myst_heading_anchors = 2
80+
myst_footnote_transition = True
81+
myst_dmath_double_inline = True
82+
myst_enable_checkboxes = True
83+
84+
# -- HTML output -------------------------------------------------
85+
86+
html_theme = 'sphinx_rtd_theme'
87+
html_title = ""
88+
89+
# Add any paths that contain custom static files (such as style sheets) here,
90+
# relative to this directory. They are copied after the builtin static files,
91+
# so a file named "default.css" will overwrite the builtin "default.css".
92+
html_static_path = ["_static"]
93+
94+
html_context = {
95+
"current_version": version,
96+
}

0 commit comments

Comments
 (0)