documentation - 记录 yaml

Question

关闭。这个问题不满足Stack Overflow guidelines .它目前不接受答案。












想改善这个问题吗？更新问题，使其成为 on-topic对于堆栈溢出。

3年前关闭。




Improve this 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: Template with YAML metadata

How to specify YAML metadata in Markdown for Pandoc Beamer slides?