Examples in H2Integrate

Examples in H2Integrate

As we continue to develop H2Integrate there are lots of example being added to the examples dir. Each time a new example is added there are often 5-9 new files added. It's always a challenge to curate a set of examples that help the user understand the tool functionality and that aren't overly simplistic.

Right now the examples are additionally being used as integration tests for new technologies and systems (test_all_examples.py).

When we do framework development that changes how inputs are organized, the PR's for those changes can easily balloon to 40+ file changes. While the changes are rather simplistic often in the YAML files, it does take time to modify all the examples.

Additionally, many of the examples are fairly copy paste or simplistic implementations of one or two technologies and we are missing examples that showcase functionality (the combiner for electricity).

Do we want to continue to have an example for every new technology?

Should we move integration tests out of test_all_examples.py?

How can we improve documentation so that we can best help users?

Proposed solution

I think we should remove some of the more simplistic examples and make the readthedocs more robust.

Alternatives considered

Additional context

Start by reviewing the examples directory and test_all_examples.py to understand how examples currently serve as integration tests. Then inspect the Read the Docs content and existing examples to identify the scope of documentation and test changes. Done should include an agreed approach for which examples remain, where integration tests belong, and how user-facing functionality is documented.