Unify YAML code listings

[mrbojangles3]

YAML listings should:

• be valid YAML objects
• Have line numbers
• Have a file name

[qmonnet]

Side note on YAML validation:

Would be great to validate the YAML snippets in CI, although on a quick search I haven't found a great solution to extract them from the Markdown files.

There are some Python scripts/packages around, but we don't really use Python elsewhere; we could have it just in CI, but the issue remains that I'm not sure these scripts handle Mkdocs options for fenced code blocks anyway (line numbering directives etc. will likely mess up with parsing).

Another option would be to have all snippets as stand-alone files and include them from the docs, but this is not realistic either, it will make it way too complex to read the sources especially for smaller snippets.

So I don't know 🤷 Maybe come up with our own tool when we get cycles for that

[mrbojangles3]

our docs system does allow for direct file inclusion, then perhaps a simple find *.yaml and run it through a linter would work. but for now I am going by hand.

[qmonnet]

perhaps a simple find *.yaml and run it through a linter would work

It would require having all YAMLs as separate files. Sometimes it makes sense, but for small snippets not really, and it makes it more difficult to read the source Markdown if you've got to juggle between files to see the examples, so that doesn't sound ideal to me 😕