Add a users guide to streamline resource framework

[DavidLegg]

• Tickets addressed: N/A
• Review: By file
• Merge strategy: Merge (no squash)

Description

This guide is meant to be a fairly condensed guide on how to use the streamline framework, organized primarily by worked example use cases, with some reference material.

The use cases were kindly provided by @bashbash, motivated by her early experience using Aerie with CADRE.

The only code change adds explicit support for "timer" style VariableClock resources, which tick down instead of up, through a few static methods. We could always get similar behavior from a stopwatch that ticked up to a positive time limit, but ticking down to zero is sometimes more intuitive.

Verification

N/A

Documentation

N/A

Future work

Continuing to aggregate explanations and worked examples. In particular,

• For unstructured resources, which are currently only brushed over briefly. In particular, showing how to integrate SPICE or model something complex like an exponential, which are two use cases I called out but didn't demonstrate, would be good.
• For unit-awareness features, which are currently omitted from the users guide entirely. This is intentional, as I don't feel fully comfortable with how unit awareness works currently. I'd like to take another run at those, focused on user-friendliness and extensibility, before we sink a lot of effort into describing how they currently work.

[dandelany]

Thanks @DavidLegg - @mattdailis & I discussed this yesterday and I've been working my way through reading it. Very well written with lots of great use-cases, thank you! I didn't have time to test & tinker with all of the code examples, and I think this could still use a read-through from others (@cohansen or @adrienmaillard or @mattdailis) with an eye towards the fine details. That said, this is super valuable and meets the standards for new docs, especially for contrib, so I'm going to approve and merge so that it can be included with the Aerie 2.17.0 release.