Improve PEcAn.SIPNET package/model documentation and connect PEcAn.SIPNET README to PEcAn book

[dlebauer]

Description

Note to new contributors: Thank you for considering this task! This is larger than many “good first issues.” You are welcome to turn a subset of steps into a sub-task and take that on. And please reach out on Slack for guidance!

The PEcAn model READMEs and documentation are minimal and mostly include generic template material. This issue focuses on the PEcAn.SIPNET model docs because:

1. SIPNET is one of PEcAn’s exemplar model couplers, and
2. The standalone SIPNET documentation is relatively up to date: https://pecanproject.github.io/sipnet

Current limitations:

• The SIPNET docs in the PEcAn book (https://pecanproject.github.io/pecan-documentation/develop/models-sipnet.html) have missing fields (e.g. homepage, authors) and still contain generic template text.
• The PEcAn.SIPNET README is very sparse.
• Information is split between the README and the PEcAn book page, and it’s not clear how they relate.

The goal of this issue is to:

• Improve the PEcAn.SIPNET README so it actually describes SIPNET and how it’s used via PEcAn, and
• Use the README content directly for the SIPNET model page - either by importing README content into the PEcAn documentation directly, or by linking out to the PEcAn.SIPNET package docs,
• Document the process so it can be applied to other models later.

Key links

• PEcAn.SIPNET package in PEcAn repository:
  https://github.com/PecanProject/pecan/tree/develop/models/sipnet
• PEcAn.SIPNET package pkgdown docs:
  https://pecanproject.github.io/package-documentation/develop/PEcAn.SIPNET/index.html
• SIPNET page in PEcAn documentation (book):
  • code: in PEcAn repository: book_source/03_topical_pages/05_models/sipnet.Rmd
  • in docs: https://pecanproject.github.io/pecan-documentation/develop/models-sipnet.html
• SIPNET repository:
  https://github.com/PecanProject/sipnet
• SIPNET documentation:
  https://pecanproject.github.io/sipnet

Tasks

1. Consolidate and update PEcAn.SIPNET docs (README)

   • Locate the PEcAn.SIPNET README source file (usually README.Rmd or README.md) under models/sipnet/.
   • Combine relevant information from the PEcAn book SIPNET page into the PEcAn.SIPNET README.md (e.g., authors, homepage, model summary).
   • Add a short “What is SIPNET?” section that summarizes the model and points to the standalone SIPNET docs, using text consistent with (but summarized from) https://pecanproject.github.io/sipnet.
   • Add a brief “Using SIPNET via PEcAn” section, including a link to the Demo_1 tutorial (or another appropriate getting-started example).
   • Confirm that links and references are up to date (e.g., SIPNET docs URL, GitHub repo, etc.).
   • Remove or replace old instructions for sipnet_unk and sipnet_r136 tarballs; instead, point readers to the current SIPNET install docs and/or recommended installation path.
     • https://github.com/PecanProject/pecan/blob/develop/book_source/03_topical_pages/05_models/sipnet.Rmd
     • https://github.com/PecanProject/pecan/blob/develop/book_source/03_topical_pages/93_installation/03_install_OS/06_install_models/install_SIPNET.Rmd#L5

2. Connect PEcAn book SIPNET page to the updated docs

   • Replace remaining generic/template text (e.g., “Introduction about model…”) with concise, real content based on the updated README and SIPNET docs.
   • Ensure the page includes clear links to:
     • The standalone SIPNET docs (https://pecanproject.github.io/sipnet), and
     • The PEcAn.SIPNET pkgdown site (https://pecanproject.github.io/package-documentation/develop/PEcAn.SIPNET/index.html).
   • Avoid duplicating long descriptions: prefer short summary + links to the README/pkgdown where detailed usage lives.

3. Validate that everything builds and links correctly

   • Build the PEcAn book locally (or run the documented build command for the docs).
   • Confirm that:
     • The SIPNET page renders without template placeholders.
     • The updated README content appears on the PEcAn.SIPNET pkgdown homepage.
     • All added links work.

4. Document the process for other model couplers

   • Add a short page or section to the PEcAn documentation (e.g., under Developer Guide or Documentation Guide) describing:
     • How the model-specific book page, package README, and pkgdown site fit together.
     • The steps you followed here to update SIPNET docs.
   • If necessary, update the README in the models/template repository to reflect the desired structure
   • Link this new documentation-maintenance page from the Developer Guide so future contributors can follow the same pattern for other models.

[Eshaan-byte]

Hi @dlebauer! I'm interested in taking on this issue to improve the PEcAn.SIPNET documentation.

I've reviewed the current state of the documentation and can see the gaps clearly:

• The README is very sparse with placeholder text
• The PEcAn book SIPNET page has empty fields and outdated installation instructions
• The standalone SIPNET docs are comprehensive but not well-connected to the PEcAn docs

I'd like to start with Task 1: Consolidate and update PEcAn.SIPNET docs (README) and work my way through the other tasks. My approach would be:

1. Enhance the README with:

   • A proper "What is SIPNET?" section based on the standalone docs
   • A "Using SIPNET via PEcAn" section with tutorial links
   • Updated/relevant installation guidance

2. Update the book page to remove template text and add proper metadata

3. Ensure all links are working and the documentation builds correctly

4. Document the process for future model documentation updates

Would you be able to assign this to me?

Thanks!

[divine7022]

Hi @Eshaan-byte! Thanks for your interest and for taking the time to review the documentation thorough, approach looks solid.
I am assigning this to you now. Feel free to open a PR