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,60 @@
+# 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 be the most comprehensive source 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 (inputs/outputs).
+-   **Installation**: Clear steps for installing both the R package and the underlying model binary.
+-   **Documentation Links**: Links to the `pkgdown` site, book chapter, and source code.
+
+### 2. PEcAn Book Chapter
+The book chapter should be a concise summary. **Do not duplicate long descriptions from the README.** Instead:
+-   Provide the standard "Model Information" table.
+-   Give a short introductory paragraph.
+-   List model-specific configuration file patterns.
+-   Link out to the `README.md` and the `pkgdown` site for detailed usage information and tutorials.
+
+### 3. Pkgdown Site
+This is automatically generated. Ensure that your `README.md` is well-formatted and that your R functions have complete Roxygen documentation.
+
+## Updating a Model Coupler's Documentation
+
+If you are updating documentation for a model (like SIPNET), follow these steps:
+
+1.  **Locate the README:** Usually found at `models/[modelname]/README.md`. 
+    - *Tip:* Use the [models/template/README.md](https://github.com/PecanProject/pecan/tree/develop/models/template/README.md) as a starting point.
+2.  **Locate the Book Source:** Found in `book_source/03_topical_pages/05_models/[modelname].Rmd`.
+3.  **Consolidate and Clean:**
+    -   Combine relevant info from old book text into the new README.
+    -   Add links to standalone model docs (e.g., [https://pecanproject.github.io/sipnet](https://pecanproject.github.io/sipnet)).
+    -   Ensure the "Using via PEcAn" section includes a link to the [Basic Run Demo](https://pecanproject.github.io/pecan-documentation/develop/rendered-demo-notebooks/run_pecan.html).
+4.  **Verify and Build:**
+    -   Commit changes and check that links point to the `develop` branch.
+    -   Ensure 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,27 @@
 
 | 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 for coupled carbon, water, nitrogen, and trace greenhouse-gas (N₂O, CH₄) dynamics. 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 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/). 
 
-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/).
+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. The `PEcAn.SIPNET` package handles this translation via its functions documented on the pkgdown site.
 
 **Model configuration files**
 
@@ -34,4 +34,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

@@ -1,100 +1,69 @@
-A generic template for adding a new model to PEcAn
-==========================================================================
-
-Adding a new model to PEcAn in a few easy steps:
-
-1. add modeltype to BETY
-2. add a model and PFT to BETY for use with modeltype
-3. implement 3 functions as described below
-4. Add tests to `tests/testthat`
-5. Update README, documentation
-6. Update Dockerfile and model_info.json
-7. execute pecan with new model
-
-
-### Three Functions
-
-There are 3 functions that will need to be implemented, each of these
-functions will need to have MODEL be replaced with the actual modeltype as
-it is defined in the BETY database.
-
-* `write.config.MODEL.R`
-
- This will write the configuratin file as well as the job launcher used by
- PEcAn. There is an example of the job execution script in the template
- folder. The configuration file can also be a template that is found based
- on the revision number of the model. This should use the computed results
- specified in defaults and trait.values to write a configuration file
- based on the PFT and traits found.
-
-* `met2model.MODEL.R`
-
- This will convert the standard Met CF file to the model specific file
- format. This will allow PEcAn to create metereological files for the
- specific site and model. This will only be called if no meterological
- data is found for that specific site and model combination.
-
-* `model2netcdf.MODEL.R`
-
- This will convert the model specific output to NACP Intercomparison
- format. After this function is finished PEcAn will use the generated
- output and not use the model specific outputs. The outputs should be
- named YYYY.nc
-
-### Dockerization
-
-The PEcAn system is leveraging Docker to encapsulate most of the code.
-This will make it easier to share new model with others, without them
-having to compile the models. The goal is for people to be able to
-launch the model in docker, and it will register with PEcAn and is
-almost immediatly available to be used. To accomplish this you will need to modify two files.
-
-* `Dockerfile`
-
- The [Dockerfile](https://docs.docker.com/engine/reference/builder/) is
- like the Makefile for docker. This file is split in two pieces the
- part at the top is to actually build the binary. This is where you
- specify all the libraries that are needed, as well as all the build
- tools to compile your model. The second part, starting at the second
- `FROM` line, is where you will install only the libraries needed to
- run the binary and copy the binary from the build stage, using the
- `COPY --from` line.
-
-* `model_info.json`
-
- The model_info.json describes the model and is used to register the
- model with PEcAn. In the model_info.json the only fields that are
- really required are those at the top: `name`, `type`, `version` and
- `binary`. All other fields are optional but are good to be filled
- out. You can leave `version` and `binary` with the special values
- which will be updated by the Dockerfile.
-
-Once the image can be build it can be pushed so others can leverage
-of the model. For PEcAn we have been using the following naming scheme
-for the docker images: `pecan/model-<model>-<model_version>:<pecan_version>`
-where the `model` and `model_version` are the same as those used to
-build the model, and `pecan_version` is the version of PEcAn this
-model is compiled for.
-
-### Additional Changes
-
-* `README.md` 
-
-This file should contain basic background information about the model. 
-At a minimum, this should include the scientific motivation and scope, 
-name(s) of maintainer(s), links to project homepage, and a list of a few
-key publications. 
-relevant publications.
-
-* `/tests/testthat/`
-
-Each package should have tests that cover the key functions of the package, 
-at a minimum, the three functions above.
-
-* documentation
-
-Update the `NAMESPACE`, `DESCRIPTION` and `man/*.Rd` files by running 
-
-```r
-devtools("models/<modelname>/")
+# 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:**
+- [Demo 1: Basic PEcAn Run](https://pecanproject.github.io/pecan-documentation/develop/rendered-demo-notebooks/run_pecan.html)
+- [MODEL in the PEcAn Book](https://pecanproject.github.io/pecan-documentation/develop/models-MODEL.html)
+
+### Model Configuration Files
+
+MODEL is configured using [X] files which are placed in the run folder, along with any necessary input links:
+
+* **`config.in`**: [Description of function and where template lives in `inst/`]
+* **`params.file`**: [Description]
+
+## 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)