Update SIPNET documentation. Fixes #3703

CHANGELOG.md

@@ -10,6 +10,7 @@ For more information about this file see also [Keep a Changelog](http://keepacha
 
 ### Added
 - Add `format_try_for_ma()` and `try_trait_mapping()` to `PEcAn.data.remote` to convert trait data from the external TRY database into the tabular format required by the PEcAn meta-analysis module (#3717).
+- Standardized PEcAn.SIPNET documentation across README, PEcAn Book, and pkgdown, and added a new ["Model Documentation Maintenance"](https://pecanproject.github.io/pecan-documentation/develop/model-documentation-maintenance.html) guide to the Developer Guide (#3703).
 - Add function `qsub_sda()` for submitting SDA batch jobs by splitting a large number of sites into multiple small groups of sites (#3634).
 - Add function `PEcAn.MA::meta_analysis_standalone` to run meta-analysis without database or file IO.
 - Added Demo 03: Meta Analysis Quarto notebook (`documentation/tutorials/Demo_03_Meta_Analysis/meta_analysis.qmd`) to demonstrate how to perform Bayesian meta-analysis and visualize posterior distributions using pre-generated trait data.

book_source/02_demos_tutorials_workflows/05_developer_workflows/00_developer_guide.Rmd

@@ -6,3 +6,4 @@ Get started with PEcAn development with this guide. You'll learn how to use Git
 * [Update PEcAn Code](#pecan-make)
 * [PEcAn and Git](#pecan-git)
 * [Coding Practices](#coding-practices)
+* [Model Documentation Maintenance](#model-documentation-maintenance)

book_source/02_demos_tutorials_workflows/05_developer_workflows/07_model_documentation.Rmd

@@ -0,0 +1,47 @@
+# Model Documentation Maintenance {#model-documentation-maintenance}
+
+This guide describes how to maintain and update the documentation for PEcAn model couplers. For every ecosystem model integrated with PEcAn, there are three primary documentation locations that should be kept in sync:
+
+1.  **Package README (`models/[modelname]/README.md`):** This is the entry point for someone visiting the PEcAn repository or the `pkgdown` site.
+2.  **Model Pkgdown site:** Generated from the README and function documentation using the `pkgdown` package.
+3.  **PEcAn Book Page (`book_source/03_topical_pages/05_models/[modelname].Rmd`):** This is part of the central PEcAn documentation (the "Book") and should focus on how the model fits into the overall PEcAn workflow.
+
+## Documentation Structure
+
+To avoid duplication, follows these guidelines:
+
+### 1. Package README (`README.md`)
+The README should serve as a concise entry point for a specific model coupler. It should include:
+-   **What is [MODEL]?**: A brief summary of the standalone model.
+-   **Standalone Documentation Link**: Point users to the official docs for the underlying model logic.
+-   **Homepage & Source**: Links to the model's primary home and repository.
+-   **Using via PEcAn**: A high-level description of what the PEcAn coupler does.
+-   **Installation**: Clear steps for installing both the R package and the underlying model binary.
+-   **Documentation Links**: Links to the `pkgdown` site, and most importantly, the PEcAn book chapter for detailed information.
+
+### 2. PEcAn Book Chapter
+The book is the right place to present detailed information about the model coupler. It should be the comprehensive source. It should include:
+-   Provide the standard "Model Information" table.
+-   Give a comprehensive introduction explaining how the model fits into PEcAn.
+-   List and detail model-specific configuration and input file patterns.
+-   Link out to standalone model documentation or vignettes if available. Do not link out to the README for detailed information—the book itself should be the master resource.
+
+### 3. Pkgdown Site
+This is automatically generated. Ensure that your `README.md` is well-formatted and that your R functions have complete Roxygen documentation.
+
+When updating an existing model coupler's documentation, ensure it follows the structure described above. After making changes, verify that your links point to the `develop` branch where appropriate, and ensure both the book and pkgdown site render correctly (build instructions below).
+
+## Build Instructions
+
+### Building the PEcAn Book
+To build the book locally:
+```bash
+cd book_source
+make
+```
+
+### Building Pkgdown site
+To build a specific package's documentation:
+```r
+pkgdown::build_site("models/[modelname]")
+```

book_source/03_topical_pages/05_models/sipnet.Rmd

@@ -2,27 +2,31 @@
 
 | Model Information ||
 | -- | -- |
-| Home Page | https://pecanproject.github.io/sipnet |
-| Source Code | https://github.com/PecanProject/sipnet |
-| License | BSD 3-Clause |
+| Home Page | [https://pecanproject.github.io/sipnet/](https://pecanproject.github.io/sipnet/) |
+| Source Code | [https://github.com/PecanProject/sipnet](https://github.com/PecanProject/sipnet) |
 | Authors | Michael Longfritz, William Sacks, David Moore, John M. Zobitz, Bobby H. Braswell, David S. Schimel, Rob Kooper, Michael C. Dietze, Istem Fer, Chris Black, David S. LeBauer|
 | PEcAn Integration | Michael Dietze, Rob Kooper |
+| PEcAn package | [PEcAn.SIPNET pkgdown site](https://pecanproject.github.io/package-documentation/develop/PEcAn.SIPNET/index.html) |
 
 **Introduction**
 
-SIPNET (Simplified Photosynthesis and Evapotranspiration Model) is a lightweight ecosystem model designed to simulate complex environmental dynamics. It tracks carbon, water, nitrogen, and trace greenhouse-gas (N₂O, CH₄) interactions, supporting applications from forest carbon inventories to managed croplands.
+SIPNET (Simplified Photosynthesis and Evapotranspiration Model) is a lightweight ecosystem model designed to simulate complex environmental dynamics. It tracks carbon, water, nitrogen, and trace greenhouse-gas (N₂O, CH₄) interactions, supporting applications from forest carbon inventories to managed croplands. It was built for data-assimilation workflows with eddy-covariance observations.
 
 Key features include simulation of photosynthesis, respiration, allocation, soil water, soil temperature, and nitrogen cycling on sub-daily time steps. The model tracks vegetation, litter, soil, and mineral-N pools, and includes event-based management for agricultural processes.
 
-For model documentation including model structure, user guide, and developer guide, see the [SIPNET documentation](https://pecanproject.github.io/sipnet). For PEcAn.SIPNET documentation, see the [package website](https://pecanproject.github.io/package-documentation/develop/PEcAn.SIPNET/).
+For comprehensive information about the standalone model structure, configuring it directly, and input/output descriptions, please visit the [Standalone SIPNET Documentation](https://pecanproject.github.io/sipnet/). 
+
+To use SIPNET through PEcAn and learn about its integration functions, please review the [PEcAn.SIPNET pkgdown site](https://pecanproject.github.io/package-documentation/develop/PEcAn.SIPNET/index.html) and its [README](https://github.com/PecanProject/pecan/tree/develop/models/sipnet#readme).
 
 **PEcAn configuration file additions**
 
-Should list the model specific additions to the PEcAn file here
+For basic SIPNET usage via PEcAn, please refer to the [PEcAn Basic Run Demo](https://pecanproject.github.io/pecan-documentation/develop/rendered-demo-notebooks/run_pecan.html).
 
 **Model specific input files**
 
-List of inputs required by model, such as met, etc.
+SIPNET requires meteorology files to be translated into its specific driver format (`.clim`). The `PEcAn.SIPNET` package handles this translation via its functions (`met2model.SIPNET`) documented on the pkgdown site. The `.clim` format is a space-delimited text file that includes variables like temperature, precipitation, vapor pressure deficit, and radiation at each timestep.
+
+Additionally, SIPNET understands event files (e.g. `events.in`) for management actions such as planting, harvest, and irrigation. When configured within the PEcAn workflow, the coupler will also read from and properly initialize state variables based on input files for phenology, soil carbon/nitrogen, and initial condition (IC) pools.
 
 **Model configuration files**
 
@@ -34,4 +38,4 @@ SIPNET is configured using 3 files which are placed in the run folder, as well a
 
 **Installation notes**
 
-For current SIPNET installation instructions, please see the [SIPNET Installation Guide](https://pecanproject.github.io/sipnet/install.html) or install binaries from the official [releases](https://github.com/PecanProject/sipnet/releases) page.
+For current SIPNET installation instructions, please see the [SIPNET Quick-Start Guide](https://pecanproject.github.io/sipnet/user-guide/getting-started/) or install binaries from the official [releases](https://github.com/PecanProject/sipnet/releases) page.

models/sipnet/README.md

@@ -58,7 +58,7 @@ install_github('pecanproject/pecan', subdir = "models/sipnet")
 
 ### Install SIPNET Model
 
-To use PEcAn.SIPNET, you also need the SIPNET model executable installed on your system. You can download precompiled versions from the SIPNET [releases page](https://github.com/PecanProject/sipnet/releases), or [download the code](https://github.com/PecanProject/sipnet) from Github and compile it yourself following the official [instructions](https://github.com/PecanProject/sipnet/blob/master/docs/user-guide/getting-started.md).
+To use PEcAn.SIPNET, you also need the SIPNET model executable installed on your system. You can download precompiled versions from the SIPNET [releases page](https://github.com/PecanProject/sipnet/releases), or [download the code](https://github.com/PecanProject/sipnet) from Github and compile it yourself following the official [SIPNET Quick-Start Guide](https://pecanproject.github.io/sipnet/user-guide/getting-started/).
 
 ## Documentation
 

models/template/README.md

@@ -98,3 +98,72 @@ Update the `NAMESPACE`, `DESCRIPTION` and `man/*.Rd` files by running
 ```r
 devtools("models/<modelname>/")
 ```
+
+---
+**NOTE: Read the instructions above and delete them when done.**
+**Below is the boilerplate README template to fill out for your model:**
+---
+
+# PEcAn.MODEL
+
+<!-- badges: start -->
+
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) 
+[![PEcAn.MODEL status badge](https://pecanproject.r-universe.dev/badges/PEcAn.MODEL)](https://pecanproject.r-universe.dev/PEcAn.MODEL)
+
+<!-- badges: end -->
+
+PEcAn Functions for the MODEL model.
+
+## What is MODEL?
+
+[Add a brief (1-2 sentence) description of the ecological model here.]
+
+For full details about the model logic, compiling the source, inputs, and outputs, please see the **[Standalone MODEL Documentation](URL_TO_STANDALONE_DOCS)**.
+
+* **Homepage**: [URL_TO_HOMEPAGE](URL_TO_HOMEPAGE)
+* **Source Code**: [URL_TO_SOURCE](URL_TO_SOURCE)
+* **Authors**: Maintainer Name, Original Author Name (PEcAn Integration)
+* **License**: [e.g. BSD 3-Clause]
+
+## Using MODEL via PEcAn
+
+The `PEcAn.MODEL` package provides the necessary functions to generate configuration files and process outputs for MODEL within the PEcAn workflow. 
+
+**Getting Started:**
+- [Link to a demo or vignette that lets a user who has already run Demo 1 get started with this model. If no such demo exists, consider including a brief tutorial directly in this README.]
+- [MODEL in the PEcAn Book](https://pecanproject.github.io/pecan-documentation/develop/models-MODEL.html)
+
+
+## Installation
+
+### Install PEcAn.MODEL Package
+
+You can install the development version of `PEcAn.MODEL` from R-universe:
+
+``` r
+# Enable repository from pecanproject
+options(repos = c(
+  pecanproject = 'https://pecanproject.r-universe.dev',
+  CRAN = 'https://cloud.r-project.org'))
+# Download and install PEcAn.MODEL in R
+install.packages('PEcAn.MODEL')
+```
+
+Or you can install directly from GitHub using the `remotes` package:
+
+``` r
+library(remotes)
+install_github('pecanproject/pecan', subdir = "models/template")
+```
+
+### Install MODEL Model
+
+To use PEcAn.MODEL, you also need the MODEL model executable installed on your system. Refer to the [MODEL installation guide](URL_TO_INSTALLATION_GUIDE) for instructions.
+
+## Documentation
+
+- **PEcAn.MODEL pkgdown site:** [https://pecanproject.github.io/package-documentation/develop/PEcAn.MODEL/index.html](https://pecanproject.github.io/package-documentation/develop/PEcAn.MODEL/index.html)
+- **Standalone MODEL Docs:** [URL_TO_STANDALONE_DOCS](URL_TO_STANDALONE_DOCS)
+- **PEcAn Book - MODEL Chapter:** [https://pecanproject.github.io/pecan-documentation/develop/models-MODEL.html](https://pecanproject.github.io/pecan-documentation/develop/models-MODEL.html)
+- **Source Code:** [https://github.com/PecanProject/pecan/tree/develop/models/template](https://github.com/PecanProject/pecan/tree/develop/models/template)