Add examples as separate pages

[s-makin]

Proposed Commit Message

docs: split example page into example library

*What does it do?*
Create a single library of yaml examples. There are currently
examples in three places:
- the modules page
- doc/examples
- the yaml examples page

Here I collect ALL existing examples into a single "example library".
The yaml examples page is now a landing page/directory.

* Examples grouped (roughly) by operation or function.
* Standardised formatting across pages.
* Links to relevant module(s) included on all pages.
* Comments extracted from yaml files for better formatting.

Note: not all examples have descriptive titles or explanations
(yet). To be addressed in future work.

*Why is this done?*
* Improved module discoverability/usability for newer users.
* Streamlining.
  - We can now remove examples from the modules page, instead linking to
    relevant examples in the library. We can then remove tabs on the module
    page, to facilitate use of ctrl+f searching for long-time users.
  - We can remove the examples from `doc/examples`, so that examples are
    all in a single place. 

Merge type

• Squash merge using "Proposed Commit Message"
• Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

[TheRealFalcon]

Overall, this is a really good change. I left comments inline.

Beyond those I do have a few other concerns.

1. While I think we're certainly aiding "browseability" here, I do wonder if we're harming "findability". If I already have an idea of what I'm looking for, rather than searching through a big examples page, I would now need to find the right section heading and hope something I might be looking for lives under the right page, and if not, I might have to do a lot of clicking around.
2. The modules examples vs the dedicated examples page served different purposes in my mind. The modules examples were about a basic "here's how to use some of relevant keys in isolation", whereas the examples page was more about "here's how to accomplish a larger common goal". Even though there was a large amount of overlap between the two, I worry that having modules linking to the examples library might diminish the simple and isolated use case over time...and now that I think of it, some of my suggestions in the inline comments to combine pages might not work if we need to link to them from different modules.

Neither of these concerns are blockers, but I do think they are things we should keep thinking about as our documentation evolves.

[s-makin]

Overall, this is a really good change. I left comments inline.

Thanks for the thorough review James, and sorry again for the size of the change. I think both of the concerns you raise are totally valid.

One thing we could do to address the first one is to make this transition in two stages - leave the original examples page in-situ, and add this "library" separately (instead of replacing the one with the other). In that way, we can track how they are used over time and give users time to adjust. It will look a bit weird as a setup to anyone driving past, but would allow us to gauge whether the library is an improvement.

The examples shown on the modules page haven't changed - and the same examples are also in the examples library (i.e., duplicated from the same yaml source files, following the module generation overhaul). It's not necessary for us to remove the module page examples, but since there have been some concerns raised about the tab setup we currently have making it hard to ctrl+f through the content it is something I've been thinking about how to solve. I think we could; 1) remove the examples from the module page and instead provide links to all relevant examples in the library, 2) keep the examples on the module page but also provide links to the examples library or 3) keep the content of the module page exactly as it is (with no added links), but rethink the presentation. Currently I'm leaning towards the third option - in my mind the module page and library serve two distinct use cases, rather than being cross-supporting. The library is intended to help newer users to discover what modules they should be looking at according to the task they want to accomplish (which is why I linked to the modules from the library but not vice versa). More experienced users already know how to find what they're looking for.

Sorry for the tl:dr lol, let me know what you think

[TheRealFalcon]

Way fewer comments this time 😃

One thing we could do to address the first one is to make this transition in two stages - leave the original examples page in-situ, and add this "library" separately (instead of replacing the one with the other). In that way, we can track how they are used over time and give users time to adjust. It will look a bit weird as a setup to anyone driving past, but would allow us to gauge whether the library is an improvement.

This sounds good to me.

3. keep the content of the module page exactly as it is (with no added links), but rethink the presentation. Currently I'm leaning towards the third option - in my mind the module page and library serve two distinct use cases, rather than being cross-supporting. The library is intended to help newer users to discover what modules they should be looking at according to the task they want to accomplish (which is why I linked to the modules from the library but not vice versa). More experienced users already know how to find what they're looking for.

This also sounds good to me.

[TheRealFalcon]

This explanation isn't entirely accurate. Vendors can't really directly place scripts in the vendor directory, and if they do, the user data keys mentioned here won't prevent them from running. I think this should be something more along the lines of

Control vendor data usage
***********************

Execution of [vendor data](link to our vendor data explanation page) may be controlled by the user. It may be disabled or executed with an optional prefix.

For a full list of keys...

Examples
...

and just FYI, I also filed #5765

[s-makin]

Noted - I've changed this to adopt your suggestion (albeit with some rewording to avoid use of the word "execute").