eCLM Documentation

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+      - 'docs-**'
+
+env:
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: 'pip'
+
+      - name: Install dependencies
+        run:  pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt
+
+      - name: Build eCLM doc homepage
+        working-directory: ./docs
+        run:  |
+          make clean docs
+
+      - name: Build eCLM Source Code browser
+        working-directory: ./docs
+        run:  |
+          make src-browser
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "docs/_build/html"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -6,6 +6,7 @@ src/externals/mct/Makefile.conf
 src/externals/mct/config.h
 src/externals/mct/config.log
 src/externals/mct/config.status
+docs/_build/*
 
 # Python byte-compiled / optimized / DLL files
 *.py[cod]

README.md

@@ -7,86 +7,11 @@ eCLM is based from [Community Land Model 5.0 (CLM5.0)]. It has the same modellin
 
 Unlike CLM5, there are no built-in batch scripts in eCLM. It is up to system maintainers or users to craft their own workflows by combining the basic tools in this repo plus the native tools in their respective platforms.
 
-## Installation
+> [!WARNING]
+> eCLM is still experimental and has been undergoing extensive testing. Use it at your own risk!
 
-This section shows you how to install eCLM on your local machine. If you are a user in [IBG-3] and wish to run eCLM on JSC supercomputers, please check out the [eCLM-JSC] repo.
+## Usage
 
-### Minimum system requirements
-
-* MPI 3.1
-* netCDF-C 4.7.4
-* netCDF-Fortran 4.5.2
-* PnetCDF 1.12.1
-* LAPACK
-* CMake 3.16
-* Supported compilers
-  - GCC 9.3.0
-  - Intel 19.1.2
-
-### Building eCLM
-
-1. Configure CMake build options.
-
-```sh
-# User-specific variables
-BUILD_DIR="bld"
-INSTALL_DIR="eclm"
-
-# Run cmake
-cmake -S src -B "$BUILD_DIR" \
-      -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR" \
-      -DCMAKE_C_COMPILER=mpicc \
-      -DCMAKE_Fortran_COMPILER=mpifort
-```
-
-Additionally, you may specify these optional build variables.
-
-* `CMAKE_BUILD_TYPE=DEBUG|RELEASE`. Defaults to `RELEASE`.
-* `CMAKE_PREFIX_PATH`. Semicolon-separated list of paths (i.e. *install prefixes*) where external libraries might be found. You may need to specify this if CMake cannot find some of the required libraries (e.g. NetCDF, PnetCDF, LAPACK).
-
-2. Build and install eCLM.
-
-```sh
-cmake --build "$BUILD_DIR"
-cmake --install "$BUILD_DIR"
-```
-
-### Install namelist generator Python package
-
-The namelist generator scripts require Python 3.X.
-
-```sh
-# Upgrade to latest version of pip
-python3 -m pip install --upgrade pip
-
-# Install package
-pip3 install --user ./namelist_generator
-```
-
-## Run sample test case
-
-```sh
-# Download and extract data files
-wget https://datapub.fz-juelich.de/slts/eclm/1x1_wuestebach.tar.gz
-mkdir 1x1_wuestebach
-tar xf 1x1_wuestebach.tar.gz -C 1x1_wuestebach
-
-# Generate namelists
-cd 1x1_wuestebach
-export DATA_DIR="$(pwd)"
-clm5nl-gen wtb_1x1.toml
-
-# Validate namelists
-clm5nl-check .
-
-# Run eCLM
-/path/to/eclm.exe
-```
-
-## Status
-
-eCLM has only been lightly tested; so far it could run a single-point and a regional case in Germany. Still, more work has to be done to ensure the correctness of the build process and the generated namelists. A user-friendly and lightweight approach to model configuration also has to be developed. *eCLM is still in alpha version and would not be ready for production runs anytime soon*.
+Please check the documentation at https://hpscterrsys.github.io/eCLM
 
 [Community Land Model 5.0 (CLM5.0)]: https://github.com/ESCOMP/CTSM/tree/release-clm5.0
-[IBG-3]: https://www.fz-juelich.de/ibg/ibg-3/EN/Home/home_node.html
-[eCLM-JSC]: https://icg4geo.icg.kfa-juelich.de/ModelSystems/clm/eclm-jsc

docs/FORD_options.md

@@ -0,0 +1,16 @@
+---
+project: eCLM Source Code Browser
+author: HPSC TerrSys
+doc_license: mit
+base_url: https://hpscterrsys.github.io/eCLM/src
+project_github: https://github.com/HPSCTerrSys/eCLM
+---
+
+Test 1 2 3
+
+<!--
+FORD (FORtran Documenter) project options list:
+
+https://forddocs.readthedocs.io/en/latest/user_guide/project_file_options.html#project-file-options
+-->
+

docs/INDEX.md

@@ -0,0 +1,8 @@
+# eCLM Documentation
+
+```{important}
+**Welcome!** You are viewing the first version of the documentation for eCLM. This is a living document, which means it will be continuously updated and improved. Please check back regularly for the latest information and updates.
+```
+
+```{tableofcontents}
+```

docs/Makefile

@@ -0,0 +1,15 @@
+BUILD_DIR = ./_build
+SRC_DIR = ../src
+
+all: docs src-browser
+
+docs:
+	jupyter-book build -W -n --keep-going .
+
+src-browser:
+	ford -d $(SRC_DIR) -o $(BUILD_DIR)/html/src FORD_options.md
+
+.PHONY: clean
+
+clean:
+	jupyter-book clean .

docs/README.md

@@ -0,0 +1,18 @@
+# Building eCLM Documentation
+
+If you'd like to develop and/or build the eCLM documentation, you should:
+
+1. Switch to this directory: `cd docs`
+2. Run `pip install -r requirements.txt`
+3. (*Optional*) Edit the books source files (`*.md`) in this folder. Check out the [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) for reference.
+4. Build the docs: `make clean docs`.
+5. (*Optional*) Build eCLM source code browser: `make src-browser`
+6. Launch the doc homepage on your default browser: `open _build/html/index.html`
+
+## Contributors
+
+We welcome and recognize all contributions. You can see a list of current contributors in the [contributors tab](https://github.com/HPSCTerrSys/eCLM/graphs/contributors).
+
+## Credits
+
+This project is created using the excellent open source [Jupyter Book project](https://jupyterbook.org/) and the [executablebooks/cookiecutter-jupyter-book template](https://github.com/executablebooks/cookiecutter-jupyter-book).

docs/_config.yml

@@ -0,0 +1,40 @@
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# See the documentation for help and more options: 
+# https://jupyterbook.org/customize/config.html
+
+#######################################################################################
+# Book settings
+title                       : eCLM Documentation  # The title of the book. Will be placed in the left navbar.
+author                      : HPSC TerrSys  # The author of the book
+copyright                   : "2024"  # Copyright year to be placed in the footer
+logo                        : ""  # A path to the book logo
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+sphinx:
+  config:
+    language: en
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/HPSCTerrSys/eCLM  # Online location of your book
+  path_to_book: docs    # Optional path to your book, relative to the repository root
+  branch: docs-initial  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+# Do not parse these files
+exclude_patterns: [FORD_options.md, README.md]

docs/_toc.yml

@@ -0,0 +1,59 @@
+# https://hpscterrsys.github.io/eCLM
+
+format: jb-book
+root: INDEX
+parts:
+  - caption: User's Guide
+    chapters:
+
+    - file: users_guide/introduction_to_eCLM/README
+      title: Introduction to eCLM
+      sections:
+      - file: users_guide/introduction_to_eCLM/introduction
+      - file: users_guide/introduction_to_eCLM/prerequisites
+      - file: users_guide/introduction_to_eCLM/how_to_use_this_document
+
+    - file: users_guide/building_eCLM/README
+      title: Building eCLM
+      sections:
+      - file: users_guide/building_eCLM/Ubuntu
+      - file: users_guide/building_eCLM/JSC/README
+        title: JSC
+        sections:
+        - file: users_guide/building_eCLM/JSC/prerequisites_JSC_users
+        - file: users_guide/building_eCLM/JSC/setting_up_eCLM
+      - file: users_guide/building_eCLM/Levante
+
+    - file: users_guide/case_examples/README
+      title: Running example cases
+      sections:
+      - file: users_guide/case_examples/Wuestebach
+      - file: users_guide/case_examples/NRW
+      - file: users_guide/case_examples/EURO-CORDEX
+
+    - file: users_guide/case_creation/README
+      title: Creating a custom case
+      sections:
+      - file: users_guide/case_creation/1_create_grid_file
+      - file: users_guide/case_creation/2_create_mapping_file
+      - file: users_guide/case_creation/3_create_domain_file
+      - file: users_guide/case_creation/4_create_surface_file
+      - file: users_guide/case_creation/5_modifications_surface_domain_file
+      - file: users_guide/case_creation/6_create_atm_forcings
+
+    - file: users_guide/running_eCLM/README
+      title: Running eCLM
+      sections:
+      - file: users_guide/running_eCLM/basic_commands
+      - file: users_guide/running_eCLM/case_customization
+
+    - file: users_guide/analyzing_model_output
+      title: Analyzing model output
+
+  - caption: Reference
+    chapters:
+    - file: reference/history_fields
+    - url: https://escomp.github.io/ctsm-docs/versions/release-clm5.0/html/tech_note/index.html
+      title: Technical Note
+    - url: https://hpscterrsys.github.io/eCLM/src
+      title: eCLM Source Code Browser