Skip to content

Commit cc324b6

Browse files
kvrigors-poll
kvrigor
and
s-poll
authored
Setup GitHub Action for publishing documentation (#15)
* initial setup of doc * add Makefile * remove src-browser * change branch in config.yml * update README and transfer to doc * typ-o at doc/running * comment out actions/checkout in doc.yml * do sparse checkout in doc.yml * fix typ-o and test deployment docs * split up build and deply in doc.yml * add path/name to deploy / update requirements * be more restrictive for trigger ci * add checkout in deployment step * Revert "add checkout in deployment step" This reverts commit 28b2ec3. * CI: Explicitly skip submodule update * CI: Try default actions/checkout behavior * CI: Removed environment in build step; fixed artifact name in deploy step * CI: Locked Ubuntu & Python version, changed CI trigger, disabled submodule fetching * CI: try sparse-checkout again * Trigger Build * CI: Added doc* branches to CI trigger * CI: Explicitly set dependency path * CI: Fixed typo. * CI: sparse checkout doc folder. * CI: Limit deploy job to 'master' branch --------- Co-authored-by: Stefan Poll <s.poll@fz-juelich.de>
1 parent 19458d2 commit cc324b6

File tree

14 files changed

+230
-53
lines changed

14 files changed

+230
-53
lines changed

‎.github/workflows/doc.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: TSMP2 WFE Docs
2+
3+
on:
4+
push:
5+
branches: [ 'master' ]
6+
pull_request:
7+
branches: [ 'master' ]
8+
9+
env:
10+
BASE_URL: /${{ github.event.repository.name }}
11+
12+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
13+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-24.04
21+
steps:
22+
- uses: actions/checkout@v4
23+
with:
24+
submodules: false
25+
sparse-checkout: |
26+
.github
27+
doc
28+
29+
- name: Set up Python 3.12
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: 3.12
33+
cache: 'pip'
34+
35+
- name: Install dependencies
36+
run: pip install -r ${GITHUB_WORKSPACE}/doc/requirements.txt
37+
38+
- name: Build TSMP2 WFE doc homepage
39+
working-directory: ./doc
40+
run: |
41+
make clean doc
42+
43+
- name: Upload documentation artifacts
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: "doc/_build/html"
47+
name: tsmp2_wfe_docs
48+
49+
deploy:
50+
if: github.event_name != 'pull_request'
51+
needs: build
52+
runs-on: ubuntu-latest
53+
environment:
54+
name: github-pages
55+
url: ${{ steps.deployment.outputs.page_url }}
56+
57+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
58+
permissions:
59+
pages: write # to deploy to Pages
60+
id-token: write # to verify the deployment originates from an appropriate source
61+
62+
steps:
63+
- name: Deploy to GitHub Pages
64+
id: deployment
65+
uses: actions/deploy-pages@v4
66+
with:
67+
artifact_name: tsmp2_wfe_docs

‎README.md‎

Lines changed: 5 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,16 @@
11
# TSMP2 workflow-engine
22

3-
## Introduction
4-
5-
TSMP2 workflow engine for running simulations. The following examples and descriptions are based on a coupled climate simulation case over the EUR-11 domain, but the underlying idea applies to all types of simulations, such as LES, NWP, real and idealised cases. The workflow is applicable for any model combination within the TSMP2 framework realm.
6-
7-
## Setup the workflow
8-
9-
Activate a compute project
10-
```bash
11-
# Replace PROJECTNAME with your compute project
12-
jutil env activate -p PROJECTNAME
13-
14-
# Check if $BUDGET_ACCOUNTS was set.
15-
echo $BUDGET_ACCOUNTS
16-
```
3+
[![docs](https://github.com/HPSCTerrSys/TSMP2_workflow-engine/actions/workflows/doc.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2_workflow-engine/actions/workflows/doc.yml)
174

18-
In case you are not on a [JSC](https://www.fz-juelich.de/) machine, set the shell variables `PROJECT`, `SCRATCH` (existing pathnames) and `BUDGET_ACCOUNTS` manually.
19-
Instead of setting `BUDGET_ACCOUNTS` you may also replace this variable in `ctl/control_tsmp2.sh`.
205

21-
``` bash
22-
cd $PROJECT/$USER
23-
git clone https://github.com/HPSCTerrSys/TSMP2_workflow-engine
24-
wfe_dir=$(realpath TSMP2_workflow-engine)
25-
cd ${wfe_dir}
26-
git submodule update --init
27-
```
28-
29-
## Building the model
30-
31-
The TSMP2 ( https://github.com/HPSCTerrSys/TSMP2 ) should be either already compiled (see [ReadMe TSMP2](https://github.com/HPSCTerrSys/TSMP2/blob/master/README.md)) or compiled with the following steps.
32-
33-
```bash
34-
cd ${wfe_dir}/src/TSMP2
35-
./build_tsmp2.sh --icon --eclm --parflow
36-
```
37-
38-
Adjust the components to your purpose.
6+
## Introduction
397

40-
## Run experiment
8+
TSMP2 workflow engine for running simulations. The following examples and descriptions are based on a coupled climate simulation case over the EUR-11 domain, but the underlying idea applies to all types of simulations, such as LES, NWP, real and idealised cases. The workflow is applicable for any model combination within the TSMP2 framework realm.
419

42-
If you want to store your run directory files elsewhere than here, set a simulation ID (replace `MY-SIMULATION`) and make `${wfe_dir}/run` into a symlink pointing to your new directory.
43-
``` bash
44-
cd ${wfe_dir}
45-
export sim_id=MY-SIMULATION
46-
export scratch_dir=$SCRATCH/$USER/$sim_id
47-
mkdir -p $scratch_dir/run
48-
git rm run/.gitkeep
49-
ln -snf $scratch_dir/run run
50-
```
5110

52-
Adapt resources and time in the setup-script.
53-
``` bash
54-
cd ${wfe_dir}/ctl
55-
vi control_tsmp2.sh
56-
```
11+
## Usage / Documentation
5712

58-
Start simulation
59-
``` bash
60-
./control_tsmp2.sh
61-
```
13+
Please check the documentation at https://hpscterrsys.github.io/TSMP2_workflow-engine
6214

6315
## Contact
6416
Stefan Poll <mailto:s.poll@fz-juelich.de>

‎doc/INDEX.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# TSMP2 Workflow Engine Documentation
2+
3+
```{important}
4+
**Welcome!** This documentation is currently under construction, and we are actively working to enhance its content and structure. We recognize that there may be areas that need further clarification or improvement, and we truly value any feedback or suggestions you may have. Your contributions will help us make this documentation more comprehensive, user-friendly, and effective. Any improvements, whether through additional details, corrections, or suggestions, are greatly appreciated as we strive to make this resource as helpful as possible.
5+
```
6+
7+
```{tableofcontents}
8+
```

‎doc/Makefile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
BUILD_DIR = ./_build
2+
3+
all: doc
4+
5+
doc:
6+
jupyter-book build -W -n --keep-going .
7+
8+
.PHONY: clean
9+
10+
clean:
11+
jupyter-book clean .

‎doc/_config.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
#######################################################################################
2+
# A default configuration that will be loaded for all jupyter books
3+
# See the documentation for help and more options:
4+
# https://jupyterbook.org/customize/config.html
5+
6+
#######################################################################################
7+
# Book settings
8+
title : TSMP2 WFE Documentation # The title of the book. Will be placed in the left navbar.
9+
author : HPSC TerrSys # The author of the book
10+
copyright : "2025" # Copyright year to be placed in the footer
11+
logo : "" # A path to the book logo
12+
13+
# Force re-execution of notebooks on each build.
14+
# See https://jupyterbook.org/content/execute.html
15+
execute:
16+
execute_notebooks: force
17+
18+
# Define the name of the latex output file for PDF builds
19+
latex:
20+
latex_documents:
21+
targetname: book.tex
22+
23+
sphinx:
24+
config:
25+
language: en
26+
27+
# Information about where the book exists on the web
28+
repository:
29+
url: https://github.com/HPSCTerrSys/TSMP2_workflow-engine # Online location of your book
30+
path_to_book: doc # Optional path to your book, relative to the repository root
31+
branch: doc-devel # Which branch of the repository should be used when creating links (optional)
32+
33+
# Add GitHub buttons to your book
34+
# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
35+
html:
36+
use_issues_button: true
37+
use_repository_button: true
38+
39+
## Do not parse these files
40+
#exclude_patterns: [options.md]

‎doc/_toc.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# https://hpscterrsys.github.io/TSMP2_workflow-engine
2+
3+
format: jb-book
4+
root: INDEX
5+
parts:
6+
- caption: TSMP2 WFE user guide
7+
chapters:
8+
9+
- file: user_guide/introduction_wfe/README
10+
title: Introduction to TSMP2 WFE
11+
sections:
12+
- file: user_guide/introduction_wfe/introduction
13+
- file: user_guide/introduction_wfe/concept
14+
15+
- file: user_guide/usage_wfe/README
16+
title: Usage of TSMP2 WFE
17+
sections:
18+
- file: user_guide/usage_wfe/setup
19+
- file: user_guide/usage_wfe/build
20+
- file: user_guide/usage_wfe/running
21+
22+
# - caption: Reference
23+
# chapters:
24+
# - file: reference/new
25+
# - url: https://github.com/HPSCTerrSys/TSMP2/blob/master/README.md
26+
# title: TSMP2 build system

‎doc/requirements.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
jupyter-book
2+
matplotlib
3+
numpy
4+
ghp-import

‎doc/user_guide/introduction_wfe/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Introduction to TSMP2 WFE
2+
3+
TSMP2 workflow engine for running simulations. The following examples and descriptions are based on a coupled climate simulation case over the EUR-11 domain, but the underlying idea applies to all types of simulations, such as LES, NWP, real and idealised cases. The workflow is applicable for any model combination within the TSMP2 framework realm.
4+
5+
The following section will give you an overview of the workflow engine and its concept.

‎doc/user_guide/introduction_wfe/concept.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# WFE concept
2+
3+
to be filled

‎doc/user_guide/introduction_wfe/introduction.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Workflow engine overview
2+
3+
to be filled

0 commit comments

Comments
 (0)