Skip to content

Docs: refresh "add a new technology" guide, auto-generate model overview, unify the docs build#787

Open
johnjasa wants to merge 3 commits into
NatLabRockies:developfrom
johnjasa:issues_487_375
Open

Docs: refresh "add a new technology" guide, auto-generate model overview, unify the docs build#787
johnjasa wants to merge 3 commits into
NatLabRockies:developfrom
johnjasa:issues_487_375

Conversation

@johnjasa

@johnjasa johnjasa commented Jun 18, 2026

Copy link
Copy Markdown
Collaborator

Docs: refresh "add a new technology" guide, auto-generate model overview, unify the docs build

I made three related docs changes:

  1. Rewrote docs/developer_guide/adding_a_new_technology.md to clarify when to use the generic baseclasses vs. a category-specific one, and updated the worked examples to match the current registry.
  2. Added docs/generate_model_overview.py, which runs at docs build time, walks h2integrate.core.supported_models, classifies each class by category and role, and rewrites the marker-delimited block in docs/user_guide/model_overview.md. The hand-written intro is preserved. Each bullet links to the autosummary page and appends the first sentence of the class's own docstring.
  3. Made local and Read the Docs builds use the same script. docs/build_book.sh now has a shebang, cds into its own directory, and treats rm -rf _build as opt-in via --clean. docs/_config.yml switches execute_notebooks from auto to cache so rebuilds reuse jupyter-cache. .readthedocs.yaml now invokes docs/build_book.sh via build.commands.

Section 1: Type of Contribution

  • Feature Enhancement
    • Framework
    • New Model
    • Updated Model
    • Tools/Utilities
    • Other (please describe):
  • Bug Fix
  • Documentation Update
  • CI Changes
  • Other (please describe):

Section 2: Draft PR Checklist

  • Open draft PR
  • Describe the feature that will be added
  • Fill out TODO list steps
  • Describe requested feedback from reviewers on draft PR
  • Complete Section 8: New Model Checklist (if applicable)

Type of Reviewer Feedback Requested (on Draft PR)

Implementation feedback:

  • I used cls.__dict__.get("__doc__") instead of inspect.getdoc(cls) so inherited docstrings don't leak in; classes with no docstring of their own render as a bare link. Happy to switch if you'd rather see inherited summaries.
  • The HIDDEN_MODELS, COMBINED_PERFORMANCE_AND_COST_MODELS, and COMBINED_COST_AND_FINANCIAL_MODELS sets at the top of the generator are small allow/deny lists; let me know if anything else should go in them.

Other feedback:

  • The new .readthedocs.yaml uses build.commands, including copying HTML to $READTHEDOCS_OUTPUT. Worth a once-over.

Section 3: General PR Checklist

  • PR description thoroughly describes the new feature, bug fix, etc.
  • Added tests for new functionality or bug fixes
  • Tests pass (If not, and this is expected, please elaborate in the Section 6: Test Results)
  • Documentation
    • Docstrings are up-to-date
    • Related docs/ files are up-to-date, or added when necessary
    • Documentation has been rebuilt successfully
    • Examples have been updated (if applicable)
  • CHANGELOG.md
    • At least one complete sentence has been provided to describe the changes made in this PR
    • After the above, a hyperlink has been provided to the PR using the following format:
      "A complete thought. PR XYZ", where
      XYZ should be replaced with the actual number.

Section 4: Related Issues

Resolves #375 and #487

Section 5: Impacted Areas of the Software

Section 5.1: New Files

  • docs/generate_model_overview.py
    • Walks supported_models, classifies each class by category and role, and rewrites the marker-delimited block in docs/user_guide/model_overview.md with cross-referenced bullets and docstring summaries.

Section 5.2: Modified Files

  • docs/build_book.sh
    • Added a shebang and set -euo pipefail, made it cd into its own directory, made rm -rf _build opt-in via --clean, and added a call to generate_model_overview.py.
  • docs/_config.yml
    • Changed execute_notebooks from auto to cache so unchanged cells are skipped on rebuild.
  • .readthedocs.yaml
    • Replaced the jobs.pre_build / python: / sphinx: config with build.commands that installs the package and runs bash docs/build_book.sh.

Section 6: Additional Supporting Information

N/A

@johnjasa johnjasa added the ready for review This PR is ready for input from folks label Jun 18, 2026
@johnjasa johnjasa marked this pull request as ready for review June 18, 2026 17:54
@johnjasa johnjasa requested a review from elenya-grant June 18, 2026 18:19
@johnjasa johnjasa marked this pull request as draft June 18, 2026 18:22
@johnjasa johnjasa marked this pull request as ready for review June 18, 2026 18:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready for review This PR is ready for input from folks

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant