fix: ensure yaml examples are valid and conform to format expectations

[jsstevenson]

close #2811

Ensure that YAML examples

• are valid YAML
• quote things that need to be quoted (I may have covered a few unnecessary cases, I don't remember the exact YAML rules here)
• provide keys in order (this is required for tests, I also don't remember how exhaustive the checks are so I just did it for every key)

[nataled]

Beat me to it! (I was working on this as well). I do notice that the indentation you're using is different from the examples I'm looking at. Please double check.

By the way, I wonder if the incorrect version is a holdover from a different file type. We're referring to the file being edited as a YAML file, and the file itself says 'yaml' within it (though it is not visible externally), but the actual file is a .md file.

Once this is finished, I will have additional changes. I'll stop working on my version and wait for yours to make them.

[jsstevenson]

@nataled sorry! I should've self-assigned the GH issue, I'm always quite lazy about that

I do notice that the indentation you're using is different from the examples I'm looking at. Please double check.

Could you be more specific? If you're referring to something like

- description: Protein Ontology
  examples:
    - description: OBO Format stanza showing use of PSI-MOD term in logical definition
      url: "https://proconsortium.org/app/export/obo/PR:000027653/"
  user: "http://purl.obolibrary.org/obo/pr"

vs

- description: Protein Ontology
  examples:
  - description: OBO Format stanza showing use of PSI-MOD term in logical definition
    url: "https://proconsortium.org/app/export/obo/PR:000027653/"
  user: "http://purl.obolibrary.org/obo/pr"

these are interchangeable in YAML -- generally, the important thing is to be indenting by chunks of 2, it's sort of arbitrary stylistic preference whether you do either of the above

I wonder if the incorrect version is a holdover from a different file type. We're referring to the file being edited as a YAML file, and the file itself says 'yaml' within it (though it is not visible externally), but the actual file is a .md file

Yeah, it's sort of... both? Jekyll (which is used to generate the static website) uses yaml front matter embedded within markdown files to declare page metadata in a computable form. I agree that it's not a "YAML file", strictly speaking -- it's just a YAML subsection. There are probably ways to effectively communicate this without burdening a new contributor too much.

[nataled]

Thanks for the explanation regarding the indentation. I much prefer your version.

[jamesaoverton]

Much appreciated!