记录yaml

Question

有没有类似javadoc或rdoc来记录YAML文件,以便我们可以将它提取到HTML文档中？理想情况下使用markdown语法.

Answer 1

概观

正如在问题的评论中所显示的那样,一般来说,记录YAML所需的全部内容是创建专门用于文档或元数据的YAML内容的一部分.

唯一值得注意的挑战是确定您是否希望您的文档部分符合用于记录代码的任何各种语法样式的约定(例如,Doxygen,NaturalDocs等等).

这个问题领域有各种方法.替代方法在本答案的"另请参见"部分中指出.

例

在YAML中创建元数据部分非常简单,只需创建一个内联字符串即可将所有文档转储为单个块.

  ## 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: 

  [..]

也可以看看

• https://blog.github.com/2013-09-27-viewing-yaml-metadata-in-your-documents/
• Pandoc:具有YAML元数据的模板
• 如何在Markdown中为Pandoc Beamer幻灯片指定YAML元数据？