Documenting yaml [closed]

Closed. This question is seeking recommendations for books, tools, software libraries, and more. It does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

开发者_StackOverflow社区

We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.

Closed 5 years ago.

Improve this question

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

---

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

• https://blog.github.com/2013-09-27-viewing-yaml-metadata-in-your-documents/
• Pandoc: Template with YAML metadata
• How to specify YAML metadata in Markdown for Pandoc Beamer slides?