Add interactive class hierarchy visualization to docs

[johnjasa]

Add interactive class hierarchy visualization to docs

This PR adds an autogenerated and interactive class hierarchy diagram to the developer guide documentation.
The visualization scans all Python files in the h2integrate package, extracts class definitions and inheritance relationships (excluding test and config classes), and produces a zoomable, pannable HTML graph embedded in the docs.
Classes are color-coded by category (converters, storage, resource, finance, control, transporters, etc.) and spatially clustered by category so related models group together visually. Node sizes reflect the number of child classes, making base classes visually prominent.

The script uses ast to parse the codebase, networkx to build the inheritance graph and pyvis to render the layout.
Running python docs/generate_class_hierarchy.py regenerates the figure, and it is now called automatically in build_book.sh.
Periodically we should update the html output. I've added this to the PR template for new models.

I don't think it's worth adding a test for this viz at this time; it'd be a bit of effort to figure out how to confirm the correct production and appearance of the doc.

I used Claude Opus 4.6 for this PR, mainly in the layout and formatting of the viz code.

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: 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]((https://github.com/NatLabRockies/H2Integrate/pull/XYZ)", where
    XYZ should be replaced with the actual number.

Section 3: Related Issues

None.

Section 4: Impacted Areas of the Software

Section 4.1: New Files

• docs/generate_class_hierarchy.py
  • Script that scans h2integrate/ for all non-test, non-config classes, builds an inheritance graph with networkx, and renders an interactive HTML visualization using pyvis with category-based color coding and spatial clustering.
• docs/developer_guide/class_hierarchy.html
  • Auto-generated interactive HTML output embedded in the docs via an iframe. Not intended to be edited manually.

Section 4.2: Modified Files

• docs/developer_guide/class_structure.md
  • Added an "Interactive class hierarchy" section that embeds the generated HTML diagram via an iframe, with instructions on how to regenerate it.
• docs/build_book.sh
  • Added a call to python generate_class_hierarchy.py before the Jupyter Book build so the diagram is regenerated on every doc build.

Section 5: Additional Supporting Information

• The pyvis package is a new dependency required only for doc generation (pip install pyvis). It is not needed at runtime.
• The visualization excludes all *Config dataclasses and test classes, showing only performance, cost, and other model classes.
• Only H2Integrate-native classes are shown; external bases like ExplicitComponent from OpenMDAO are excluded.

[RHammond2]

I think if the colors were refined a bit more so there were some broader classifications, the visualization would work a lot better. If there are overlappy categories, could we use different shapes or hatching to indicate this difference rather than a slightly different color. As it stands, it's hard to glean any relationships because many colors are very close. I can dig into the code itself if you'd like and come up with some recommendations, but this is my only real criticism

[johnjasa]

I think if the colors were refined a bit more so there were some broader classifications, the visualization would work a lot better. If there are overlappy categories, could we use different shapes or hatching to indicate this difference rather than a slightly different color. As it stands, it's hard to glean any relationships because many colors are very close. I can dig into the code itself if you'd like and come up with some recommendations, but this is my only real criticism

Nice, thanks for the quick feedback! I've combined the colors based on broader classifications here, let me know what you think:

[genevievestarke]

Hey John! I love this figure and I think it's an awesome way to represent H2I! Jumping on the color feedback that Rob gave, could we separate the colors for the {control, core, and electricity} and {metal and storage} groups? I think I can make out the different oranges, but the blues are especially hard.

[johnjasa]

Hey John! I love this figure and I think it's an awesome way to represent H2I! Jumping on the color feedback that Rob gave, could we separate the colors for the {control, core, and electricity} and {metal and storage} groups? I think I can make out the different oranges, but the blues are especially hard.

Great call, Gen, those don't look so distinct! I've modified the colors accordingly. How's this?

[RHammond2]

This might be an unpopular opinion, and likely nontrivial to implement, but I wonder if we could generate a few static images for the major subsets and collections of smaller subsets and embed each of them? I didn't originally notice that the image cuts off the left sidebar pretty awkwardly. Alternatively, is there a way to alter them HTML or embedding to limit the page width?

[johnjasa]

This might be an unpopular opinion, and likely nontrivial to implement, but I wonder if we could generate a few static images for the major subsets and collections of smaller subsets and embed each of them? I didn't originally notice that the image cuts off the left sidebar pretty awkwardly. Alternatively, is there a way to alter them HTML or embedding to limit the page width?

Great feedback! I've changed it so the viz doesn't cut off the table of contents on the left side, but can extend all the way right.

We could definitely make static images! But tell me more, I want to understand the value add more. Would it be in place of this interactive viz page, or in addition to it? Is the main goal to have a separated area where we can discuss subsets of the models in more detail?

[jaredthomas68]

I love this, thanks @johnjasa! Most of my thoughts while looking at it were about inconsistencies in our organization that we need to fix. I do have a couple of comments on the image itself though.

1. The colors are currently being used to represent model category (converter, storage, transport, etc), product (methanol, electricity, etc), model area (cost, performance, control), and class type (base class, child). I think it would be helpful to use different sets of things for each way we want to visually organize the information. Building on some comments above, this might look like: marker shape for class type (base class, utility, etc), hash pattern for model category (converter, storage, resource, etc), border color or type for model area (cost, performance, etc), and color for application area (steel, ammonia, electricity, etc).
2. Another way of doing 1^ might be to organize the graphs into columns according to their model category, roughly in order of execution. So, from left to right it would go something like site, resource, converter, storage, transport, finance, utilities.
3. I kind of like @RHammond2 suggestion to make separate static images of each unconnected graph set. I think it could make it more clear what is connected since some of the smaller sets get lost, but this would be incompatible with 2^

[RHammond2]

As @jaredthomas68 stated, the static images would make it easier to see the smaller, disconnected subgraphs. The relationships could also be broken up by headings and maybe introductory sentence as well (if needed). I think with the width issue being handled, I could go either way on the static images.