Clean up gitignore and consolidate examples documentation

[paulf81]

Working on Hercules recently I realized that the gitignore file was incorrectly ignore examples documentation in:

docs/examples

Looking over gitignore this was the main error, but in general the file had gotten a little haphazard over time and includes a lot of explicit ignores to files and folders no longer in the repo. This PR fixes the above issue and then does a general clean-up. Rather than delete the ignores pointed to out-dated files they're simply grouped a legacy banner for now.

The result of the fix are that the missing example docs are now tracked and included in this PR.

[Copilot]

Pull request overview

This PR fixes the .gitignore configuration so documentation examples under docs/examples are tracked again, and adds/aligns example documentation pages for the Hercules examples. It also reorganizes and modernizes the ignore rules, grouping legacy patterns under a dedicated section.

Changes:

• Un-ignore docs/examples and add detailed markdown docs for examples 00–06, aligning them with the corresponding examples/* directories.
• Restructure .gitignore into clearly labeled sections (Python, macOS, IDE, data, outputs, docs, testing, legacy) and remove/segment outdated patterns.
• Add more precise ignores for generated data, logs, caches, and legacy Hercules artifacts.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.gitignore	Cleans up and restructures ignore rules, stops ignoring docs/examples, and groups historical Hercules artifacts under a clearly marked legacy section.
docs/examples/00_wind_farm_only.md	Documents how to run and plot the simple wind-farm-only example, matching the existing examples/00_wind_farm_only setup.
docs/examples/01_wind_farm_dof1_model.md	Adds docs for the 1‑DOF wind-only example, but currently describes a manual notebook pre-step that is inconsistent with the auto-generated inputs used by the example code.
docs/examples/02_wind_farm_realistic_inflow.md	Adds docs for the realistic inflow wind-farm example; description text has a minor grammar issue.
docs/examples/02b_wind_farm_realistic_inflow_precom_floris.md	Documents the precomputed-FLORIS version of the realistic inflow example but refers to an outdated Wind_MesoToPowerPrecomFloris class instead of the current WindFarm + wake_method: precomputed configuration.
docs/examples/03_wind_and_solar.md	Adds documentation for the wind-and-solar hybrid plant example, consistent with the example README and configuration.
docs/examples/04_wind_and_storage.md	Adds documentation for the wind-plus-storage example where storage charges only from wind, in line with the corresponding example.
docs/examples/05_wind_and_storage_with_lmp.md	Provides a high-level overview of the LMP-based wind-and-storage example and its selective external data logging behavior.
docs/examples/06_wind_and_hydrogen.md	Adds detailed documentation for the wind-plus-hydrogen example, including configuration details and the hydrogen reference signal input.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The sentence "In this case uses a large set of synthetic wind data." is grammatically incorrect and a bit unclear; it should be rephrased (for example, to "This case uses a large set of synthetic wind data" or similar) for readability.

Suggested change

	In this case uses a large set of synthetic wind data.
	This case uses a large set of synthetic wind data.

[misi9170]

Thanks @paulf81 . I don't quite understand what is happening here---do we know when/why docs/examples/ was in the gitignore in the first place? Also, even though docs/examples/ is (currently) in the gitignore, there are some example files correctly in the docs, for instance this one: https://natlabrockies.github.io/hercules/examples/00_wind_farm_only.html

Do we know why/how that is? Perhaps they were already in before docs/examples/ was added to the gitignore? Do we need to clear those files from the repo somehow?

EDIT: it seems that the existing examples are building from READMEs that are in the (main) examples/ directory. I think this was by design. Are you proposing removing the readme.md files from the main examples/ directory?

[paulf81]

Thanks @paulf81 . I don't quite understand what is happening here---do we know when/why docs/examples/ was in the gitignore in the first place? Also, even though docs/examples/ is (currently) in the gitignore, there are some example files correctly in the docs, for instance this one: https://natlabrockies.github.io/hercules/examples/00_wind_farm_only.html

Do we know why/how that is? Perhaps they were already in before docs/examples/ was added to the gitignore? Do we need to clear those files from the repo somehow?

EDIT: it seems that the existing examples are building from READMEs that are in the (main) examples/ directory. I think this was by design. Are you proposing removing the readme.md files from the main examples/ directory?

I was thinking this was a copy/paste error from like the FLORIS/FLASC workflow where the examples folders are copied over during CI and built into notebooks so we don't want to track. But these being markdown I'm assuming we did. They are mostly redundant to the in-folder READMES so another option is just to remove?

[misi9170]

In Hycon, I decided to have dedicated example documentation in docs/, rather than having detailed readmes in the examples/ folder. I don't have a strong opinion either way, but I do think we should have one or the other---not a mix of detailed readmes in the examples/ directory and in the docs/examples/ directory

[paulf81]

I think the Hycon way makes sense. I can mix those together into docs/examples now in this PR if that makes sense?

[misi9170]

Sure. Let's just let @genevievestarke weigh in first, but that works for me.

[genevievestarke]

That sounds good to me, as well! If we move to a centralized example document, it would also be a good idea to have a checklist when adding a new example so it doesn't get lost. I'll look into how those can be added to a PR template!

[paulf81]

That sounds good to me, as well! If we move to a centralized example document, it would also be a good idea to have a checklist when adding a new example so it doesn't get lost. I'll look into how those can be added to a PR template!

Ok I'll get on it, thanks!

[paulf81]

Ok, last push should have implemented the consolidation of README files -> docs

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[misi9170]

Looks good to me. One thing you might consider is to add a very minimal top-level readme to the examples/ directory pointing people to the Hercules docs for information about the examples (e.g. https://github.com/NatLabRockies/hycon/blob/main/examples/readme.txt). Not critical though.

[paulf81]

Looks good to me. One thing you might consider is to add a very minimal top-level readme to the examples/ directory pointing people to the Hercules docs for information about the examples (e.g. https://github.com/NatLabRockies/hycon/blob/main/examples/readme.txt). Not critical though.

Good suggestion, I added the file

[genevievestarke]

I think it looks good, I just had a small comment about one of the example readmes! Let me know if you want to address it in this PR or later!

[genevievestarke]

This is not the focus of this PR, but could you clarify this line a little bit? I'm not sure how this is different than the case below it.

[paulf81]

I fixed the lower line to clarify it meant that in the event that some turbines are off while others are on

[paulf81]

Thanks for your comment @genevievestarke , I think I resolved the discrepancy. Good to merge for me, thank you!