Documenting yaml [closed]
Asked Answered
V

1

14

Is there something like javadoc or rdoc for documenting YAML files, so that we could extract it into HTML documentation? Ideally with markdown syntax.

Vivl answered 5/7, 2011 at 18:50 Comment(4)
YAML is for data, not for programs. Since when do we document data to that degree? A fixed schema should be documented independently of data that uses that schema. Remarks to caveats about the data at hand can go into line commnents in the file, but don't need to be compiled into an external format IMHO since they are only needed when actually viweing/editing that data.Kampong
I see you are into functional programming, so I don't need to point out the fact that the line between programs and data is not always drawn that clearly. In particular, we use yaml files to define certain tasks (several tasks may use the same code, but they do essentially different things). Say, a DSL in YAML. And the DSL needs to be commented.Phyto
Umm, no @delnan is right... "Early in its development, YAML was said to mean "Yet Another Markup Language",[3] but was retermed to distinguish its purpose as data-oriented, rather than document markup." - Wikipedia. If you are using YAML for markup, even in a DSL or something, you're breaking the very definition of YAML...Inveracity
Not sure where I suggested that we use YAML for markup? As I said, we use it as a poor man's DSL, so to say, and it serves us very well. Just need to add some meta data there as well. At the end we simply extended the schema with documentation part.Phyto
D
7

Overview

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.

Example

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: 

  [..]

See also

Derna answered 19/12, 2011 at 17:45 Comment(3)
Thanks, that's how we decided to do it as well (only with structured metadata, instead of a single string field as suggested here). We are already using it and generating HTML docs out of it.Phyto
"NOTE: YAML generally throws your comments away, so they are not very useful for round-trip metadata" +1 :-)Pissarro
Thanks for ideas. Ansible intensively uses YAML format which is no longer data only as its playbook are interpreted as program... and I am looking for a way to document them like I was used to do with perldoc.Allurement

© 2022 - 2024 — McMap. All rights reserved.