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.

[TheRealFalcon]

This doesn't really make sense. The other user data formats don't conflict with cloud-config in any way. You can pass various types, or you can pass an archive that contains both cloud-config and other types of user data and they'll generally all work together just fine.

User data in general can overwrite what was defined under a datasource configuration in base configuration, or it can overwrite vendor data, but that is all cloud-config being layed on top of other cloud-config, and I'm not sure it's relevant for this page.

[s-makin]

It looks like I accidentally committed the wrong version of this file - this is still the same as the old one. Sorry! I'll put in the one that addressed the previous feedback.

[TheRealFalcon]

I don't think it is a problem, but just note that there is overlap between this and https://cloudinit.readthedocs.io/en/latest/explanation/format.html#headers-and-content-types

[TheRealFalcon]

Should we put the link to modules here?

[TheRealFalcon]

This section isn't true. The ordering of the config can be completely arbitrary.

The state based on when modules run can have some unfortunate effects, but the ordering of your cloud-config has no relationship to the order in which modules run.

#cloud-config

users:
  - name: ubuntu
    groups: sudo
groups:
  - sudo

will have the exact same outcome as

#cloud-config

groups:
  - sudo
users:
  - name: ubuntu
    groups: sudo

[s-makin]

I removed this as a section and made the wording more accurate. I decided talking about highly specific exceptions didn't fit in this overview and would just be confusing. Anyone who looks at that module will get the full picture anyway.

[TheRealFalcon]

I don't love the framing of this paragraph. To me, cloud-config generally represents some aspect of how we want the system to be configured using declarative syntax. This is then achieved via various modules that act on that cloud-config. As much as we'd like it to be, it's not always a 1:1 mapping, so I don't want people to be confused thinking "I see a keyboard key, that means there's automatically a corresponding keyboard module". In this case it happens to be true, but for example, hostname gets acted on by several modules, and several of our top level keys don't have any direct corresponding modules.

[TheRealFalcon]

There's a looooot of explanation in this and the other apt page. Should we remove it all or move it into the module documentation?

[s-makin]

Most of the apt stuff (if not all) came from the example folder. I'm very happy to get rid of anything that's duplicated. The module docs seem like the most sensible place to document/explain the behaviour but I might need a hand to make sure I don't accidentally get rid of anything important.

[TheRealFalcon]

The other pages are all a set of independent examples separated by section headers, but this is a single example separated by section headers. Is there a way we can lay this page out differently so it's obvious this is one big example rather than a set of unrelated examples?

[s-makin]

This was my attempt to avoid having comments inside the example, but I think in this case it's unavoidable. Changed it back to how it was.

[s-makin]

Let me know if this is better

[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