Menu
Is there something like javadoc or rdoc for documenting YAML files, so that we could extract it into HTML documentation? Ideally with markdown syntax.
908
YAML is a digestible data serialization language often used to create configuration files with any programming language. Designed for human interaction, YAML is a strict superset of JSON, another data serialization language.
Items of a list in YAML are represented by preceding it with - (hyphen). Key value pairs in YAML are represented as <key>:<value> . YAML is case sensitive. YAML uses spaces and indentations to define document structure. To define a YAML file we use either .
In general the order of keys in a YAML file does not matter. Neither do blank lines. Indentation may be with any number of spaces, as long as it is consistent throughout the file.
Developer can use remote URL to save and edit the YAML files. Here are few samples of the YAML URL. Now click on these YAML samples. Once this link is open, use save as functionality of the browser and save.
As it appears in the comments to the question, generally speaking, all that is necessary for documenting YAML is to create a section of the YAML content devoted specifically to documentation or metadata.
The only noteworthy challenge is determining whether you want your documentation section to conform with the conventions of any of the various syntax-styles for documenting code (e.g., Doxygen, NaturalDocs, whatever).
There are various approaches to this problem domain. Alternate approaches are indicated in the "See also" section of this answer.
Creating a metadata section in YAML is very straightforward, you can do it simply by creating an inline string where you dump all your documentation as a single block.
## comments
## NOTE: YAML generally throws your comments away, so they are not very useful
## for round-trip metadata
meta: |
Here is all my documentation and metadata
blah blah blah.
data:
branch_one:
- caption: blah blah
date: blah blah
details: blah blah
- caption: blah two
date: blah blah
details: blah blah
branch_two:
[..]
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
