eCLM Documentation (#38)

* Docs initial commit

* Fixed wrong pip install path and added README on how to build docs

* Set full path to doc artifacts

* Try docs/_build/html

* Fixed typo on docs.yml

* Specified github-pages env var

* Added Makefile for building docs locally

* Test .ipynb notebook

* Restructured docs

* CI: Renamed upload-pages-artifact -> upload-artifact

* CI: Revert to upload-page-artifact@v2

* CI: Revert to upload-pages-artifact@v2

* CI: Supported pip caching

* CI: Add checks for dead links

* CI: Fixed wrong path for linkcheck

* Slightly modified ToC structure

* Set branch to docs-initial

* Disabled edit button

* Renamed Tutorials -> User's Guide

* Added eCLM Source Code browser

* docs.yml: Fixed working-directory path

* Uploaded FORD_options.md

* Added description for building eCLM on JSC machines

* Updated description for building eCLM on JSC machines

* Additional updates to building eCLM on JSC machines

* Added introduction to the Guide, updated toc

* Updates to INDEX and introduction

* Updated introduction and eCLM build on JSC machines

* Updated URLs

* Modified README of case_creation

* Added SCRIP grid file and mapping file creation

* Corrections to SCRIP grid file and mapping file creation

* Added creation of domain file

* Added surface file creation

* Added description for surface file creation

* Edited introduction and added 'running eCLM' to the guide

* Added descriptions for running eCLM and analyzing model output

* Added documentation on running eCLM

* Updated INDEX.md file

* Edited case examples and made a few corrections

* Added images directory and modified case creaion

* Added note on domain file creation

* corrected typo

* Fixed text that fails linkcheck; add linkcheck to default jupyterbook build

* docs.yml: Prioritize doc build over src browser

* README: Removed install steps and added link to docs

* Changed image in introduction, modified step 5 and 6 of case creation

* Updated links

* Modifed surface and domain file creation

* Fixed hyperlink

* "Edited domain file creation to include swapping of ocean and land mask"

* Updated explanations for surface and domain file modifications

* Corrected path to CSMDATA

* adding a few links to the doc

* typo fix

* link to existing resource for logging in to JSC machines

* small command fix

* remove prerequisites parts that duplicate existing startup-guide

* remove prerequisites parts that duplicate existing startup-guide II

* small style change

* docs: add `apt install` command loading Ubuntu system requirements

* docs: add `apt update` command

* docs: add `apt install` command for blas/lapack

* docs: Ubuntu `apt` calls: more structure, added Python-packages

* docs: `-r` flags for `cp` command needed

Error message:

```
cp: -r not specified; omitting directory
'/p/scratch/cslts/shared_data/rlmod_eCLM/example_cases/nrw_300x300'
```

* docs: include links to namelist variable list

* docs: mention flag `--parallel` for parallel build

---------

Co-authored-by: kvrigor <[email protected]>
Co-authored-by: Johannes Keller <[email protected]>

.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