Move inputs documentation from sources.csv to inputs/*/README.md

docs/scripts/generate_inputs_markdown.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+
+import argparse
+import os
+from pathlib import Path
+
+def _collect_input_readmes(inputs_root: Path) -> list[Path]:
+    readmes = []
+    for child in sorted(inputs_root.iterdir(), key=lambda p: p.name.casefold()):
+        if not child.is_dir():
+            continue
+        readme = child / "README.md"
+        if readme.exists():
+            readmes.append(readme)
+    return readmes
+
+
+def _write_inputs_md(output_path: Path, readmes: list[Path]) -> None:
+    lines = []
+    lines.append("# Inputs Documentation")
+    lines.append("")
+    lines.append(
+        "This page aggregates documentation from each folder README under the inputs directory."
+    )
+    lines.append("")
+    lines.append("## Table of Contents")
+    lines.append("")
+
+    for readme in readmes:
+        folder = readme.parent.name
+        lines.append(f"- [inputs/{folder}](#inputs{folder})")
+
+    # Do not add an additional markdown section header here.
+    # Each included README already contains its own heading.
+    for readme in readmes:
+        folder = readme.parent.name
+        include_rel = os.path.relpath(readme, output_path.parent).replace(os.sep, "/")
+        lines.append("")
+        lines.append(f"<a id='inputs{folder}'></a>")
+        lines.append("")
+        lines.append("```{include} " + include_rel)
+        lines.append("```")
+
+    output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main(app=None):
+    # If called from Sphinx, app is provided; otherwise support optional CLI usage.
+    if app is None:
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "--reedsPath",
+            "-r",
+            type=str,
+            default="",
+            help="Path to ReEDS repository root",
+        )
+        args = parser.parse_args()
+        if args.reedsPath:
+            repo_root = Path(args.reedsPath).resolve()
+        else:
+            # docs/scripts/generate_inputs_markdown.py -> repo root is two levels up.
+            repo_root = Path(__file__).resolve().parents[2]
+    else:
+        repo_root = Path(app.srcdir).resolve().parents[1]
+
+    inputs_root = repo_root / "inputs"
+    docs_source_root = repo_root / "docs" / "source"
+    output_path = docs_source_root / "inputs.md"
+
+    readmes = _collect_input_readmes(inputs_root)
+    _write_inputs_md(output_path, readmes)
+
+    print("inputs.md has been updated from inputs/*/README.md files")
+
+
+if __name__ == "__main__":
+    main()

docs/source/conf.py

@@ -2,7 +2,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "scripts"))
-import generate_markdown
+import generate_inputs_markdown
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -16,9 +16,9 @@
 copyright = "2024, NREL"
 author = "NLR"
 
-# --setup function to run generate_markdown.py on 'make html' ---------------------------------
+# --setup function to run generate_inputs_markdown.py on 'make html' ---------------------------------
 def setup(app):
-    app.connect("builder-inited", generate_markdown.main)
+    app.connect("builder-inited", generate_inputs_markdown.main)
 
 # -- General configuration ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/developer_best_practices.md

@@ -310,7 +310,7 @@ To edit the ReEDS documentation:
 3. Commit and push your changes as you normally would.
    - **When your pull request gets merged into main, there is a github action that will automatically recompile the documentation with your changes and publish the updated site.**
 
-Make sure to update the `docs/sources.csv` file when applicable.
+If you're updating anything related to the input files, make sure to update the relevant `inputs/*/README.md`.
 
 ### Viewing the Documentation Locally
 

docs/source/index.md

@@ -16,7 +16,7 @@ setup
 developer_best_practices
 model_documentation
 user_guide
-sources
+inputs
 postprocessing_tools
 publications
 faq