Documentation Challenge

[GbotemiB]

This Discussion board aims to track every contribution and improvement on the documentation challenge.

[GbotemiB]

1. Model-Specific Content Updates

These issues are focused on documenting the specific features and configurations of the different models.

Power Model

These tasks are centered around improving the documentation for the core electricity-only model.

• Improve documentation of power model #1309: Improve documentation of power model (Hard)
  • Ensure configuration parameters are up to date in documentation #1341: Ensure configuration parameters are up to date in documentation (Medium)
    • Update Configuration to include missing power model configs and sector-coupled configs #1377: Update Configuration to include missing power model configs (Medium).
    • Update Config tables #1378: Update Config tables (Medium)
  • Revise section model customization in readthedocs #1342: Revise section model customization in readthedocs (Medium)

Sector-Coupled Model

These tasks are specifically for adding and improving documentation related to the sector-coupled features.

• Add sector-coupled configuration to docs #1208: Add sector-coupled configuration to docs (Medium)
• Review Introduction of pypsa-earth in documentation to cover more on sector-couple. #1339: Review Introduction of pypsa-earth in documentation to cover more on sector-couple. (Medium)
• Update Configuration to include missing power model configs and sector-coupled configs #1377: Update Configuration to include missing sector-coupled configs (Medium).
• Index of read-the-docs need to be updated #1447: Update Index page of documentation to include sector-couple information (Easy)

New Tutorials (Covering Both Models)

This is a significant, high-value task that involves creating new long-form content.

• Add a tutorial elecricity and sector-coupled #1107: Add a tutorial electricity and sector-coupled (Hard)

---

2. Core Functionality & API Documentation

These issues relate to documenting the fundamental rules, scripts, and programmatic interfaces of PyPSA-Earth that apply to all models.

• Create a section in the documentation to include information about custom data in the model #1450: Add a section for custom data in the model (Medium)
• Update Rules Overview section of the documentation #1380: Update Rules Overview section of the documentation (Medium)
• Update API reference of the documentation #1379: Update API reference of the documentation (Hard)
• Document scenario running and statistics collection #730: Document scenario running and statistics collection (Hard)
• Missing config tables and docstrings for some scripts #573: Missing config tables and docstrings for some scripts (Hard)
• Add a functionalities page in the documentation #1546: Add a functionalities page in the documentation (Medium)

---

3. Structural & Usability Improvements

These issues focus on the overall structure, organization, and user-friendliness of the documentation for both new users and contributors.

• Installation Guide:
  • Improve Installation Guide Structure #1336: Improve Installation Guide Structure (Easy)
  • Re-order installation instructions #1105: Re-order installation instructions (Easy)
• Contribution & Usage Guides:
  • Standardize Usage Section Format #1338: Standardize Usage Section Format (Medium)
  • Organize Contribution Guide for Documentation #1337: Organize Contribution Guide for Documentation (Medium)
  • Engagment instructions in PR template & readthedocs #653: Engagement instructions in PR template & readthedocs (Medium)
  • Docs Migration to MkDocs #1631: Migration of the documentation to Mkdocs (Medium)

---

4. General Maintenance & Cleanup

These are smaller, well-defined tasks that improve the quality and completeness of the documentation across the board.

• Fix Grammar Issues Across Documentation #1335: Fix Grammar Issues Across Documentation (Easy)
• Mention the Open Source License in the README and/or documentation. #1317: Mention the Open Source License in the README and/or documentation. (Easy)

---

Difficulty Levels

• Easy – Little or no prior experience with PyPSA/PyPSA-Earth.
• Medium – Some familiarity with the workflow and code structure.
• Hard – Requires deep understanding of PyPSA-Earth internals.