Issue 107: lead the parser examples with runnable code

[cdgaete]

Closes #107

Changes proposed in this Pull Request

Both example pages — docs/examples/dea_storage_v10.md and docs/examples/manual_input_usa_v0134.md — opened with an Overview, a Dataset Description and a step-by-step Parser description, so the first runnable line appeared around line 75. Neither showed how the raw data becomes the parsed output.

Each page is restructured to the same shape, with the first snippet now at line 21:

• Quick start — three runnable load() snippets with their captured output: the number of technologies, the collection as a dataframe, and one parameter of one technology.
• From raw data to parsed output — a Mermaid diagram spanning the raw row's columns, the parser's stages and the resulting Technology.
• A worked row — a table tracing one real raw row to each of its parsed fields, followed by a note on the two conversions that are not evident from it.
• Parser steps in detail — the previous narrative, compressed.
• Regenerate the data and Outputs — the existing parse() snippet and its parameters, unchanged in substance.

Every code block was executed against a clean install of the built wheel from a working directory outside the repository; the text blocks are the captured output.

Checklist

• Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
• Data source for new technologies is clearly stated.
• Newly introduced dependencies are added to environment.yaml (if applicable).
• A note for the release notes doc/release_notes.rst of the upcoming release is included.
• I consent to the release of this PR's code under the GPLv3 license.

[euronion]

Thanks @cdgaete ! I really like the mermaid graphs. I'll steal this idea for other projects :)

Reading through this, it feels very dry and descriptive. I was wondering what your intended target audience is? First-time users or people looking into a documentation for a specific parser?

If it is the former (first time users), it seems a bit too detailed, e.g. the specific opinioated transformations that are being made.

If it is the second (documentation on the parsers), it feels a bit too simple / shallow. E.g. the intial examples on how to use it would not need to be repeated, instead it might make sense to include some more specific information about the data, like which technologies are covered, opinioated transformations, ...?

What's your take? Could you elaborate a bit more your target audience?

[euronion]

ping @cdgaete

[cdgaete]

Hi @euronion, thanks for the review!

The intended audience is first-time users. I see your point — some parts, like the opinionated transformations, are probably too detailed for that. But I'd argue energy modelers usually have a solid background, so the extra depth still serves them rather than overwhelming them. For now, I'd prefer to leave it as is rather than simplify.

That said, if you think trimming would help, I'm happy to get concrete guidelines on what to remove or restructure, and implement those.