Documentation structure reorganization (#65)

* Used TSMP2 to build eCLM. This vastly simplifies the build procedure.
* Updated the documentation structure
  - Created separate chapter dedicated to all aspects of running eCLM
  - Removed pages without content
  - Added external links to [TSMP2 Workflow Engine](https://hpscterrsys.github.io/TSMP2_workflow-engine/INDEX.html) and [eCLM static file generator](https://github.com/HPSCTerrSys/eCLM_static-file-generator/blob/main/README.md)

Author: kvrigor

.github/workflows/CI.yml

@@ -1,7 +1,12 @@
 name: eCLM CI Test
 
-# Controls when the action will run.
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
 
 jobs:
   eclm_build_job:

.github/workflows/docs.yml

@@ -4,7 +4,9 @@ on:
   push:
     branches:
       - master
-      - 'docs-**'
+  pull_request:
+    branches:
+      - master
 
 env:
   BASE_URL: /${{ github.event.repository.name }}
@@ -16,24 +18,18 @@ concurrency:
   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
+  build-docs:
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
           cache: 'pip'
 
-      - name: Install dependencies
+      - name: Install pip packages
         run:  pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt
 
       - name: Build eCLM doc homepage
@@ -50,7 +46,23 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           path: "docs/_build/html"
+          name: eCLM_docs
 
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+  deploy-docs:
+    if: github.event_name != 'pull_request'
+    needs: build-docs
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
+      with:
+        artifact_name: eCLM_docs

docs/INDEX.md

@@ -4,5 +4,5 @@
 **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}
-```
+eCLM is based on version 5.0 of the Community Land Model ([CLM5](https://www.cesm.ucar.edu/models/clm)) with simplified infrastructure for build and namelist generation. The build system is handled entirely by Cmake and namelists are generated through a small set of Python scripts. Similar to CLM5, eCLM is forced with meteorological data and uses numerous input streams on soil properties, land cover and land use, as well as complex parameter sets on crop phenology, and plant hydraulics for simulations.
+

docs/Makefile

@@ -1,15 +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
 
+all: docs src-browser
+
 .PHONY: clean
 
 clean:
-	jupyter-book clean .
+	jupyter-book clean .

docs/_config.yml

@@ -7,7 +7,7 @@
 # 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
+copyright                   : "2025"  # Copyright year to be placed in the footer
 logo                        : ""  # A path to the book logo
 
 # Force re-execution of notebooks on each build.

docs/_toc.yml

@@ -3,57 +3,51 @@
 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
+- caption: Introduction
+  chapters:
+  - file: users_guide/installation/README
+    title: Installing eCLM
+  - file: users_guide/introduction/introduction
+    title: Scientific Background
+
+- caption: User's Guide
+  chapters:
+  - 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/running_cases/case_customization
+    title:  Customizing eCLM namelists
+
+  - file: users_guide/analyzing_model_output
+    title: Analyzing model output
+
+  - 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
+
+- caption: Developer's Guide
+  chapters:
+  - file: users_guide/installation/source_installation
+    title: Building eCLM from source
+  - url: https://hpscterrsys.github.io/eCLM/src
+    title: eCLM Source Code Browser
+
+- caption: Reference
+  chapters:
+  - file: reference/history_fields
+  - url: https://escomp.github.io/CTSM/release-clm5.0/tech_note/index.html
+    title: CLM5 Technical Note
+  - url: https://github.com/HPSCTerrSys/eCLM_static-file-generator/blob/main/README.md)
+    title: eCLM static file generator
+  - url: https://hpscterrsys.github.io/TSMP2_workflow-engine
+    title: TSMP2 Workflow Engine