Documentation 记录yaml

是否有类似javadoc或rdoc的东西用于记录YAML文件，以便我们将其提取到HTML文档中？最好使用标记语法。

概述 正如对问题的评论中所显示的那样，一般来说，记录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: 

  [..]

另见

---

YAML用于数据，而不是程序。我们从什么时候开始将数据记录到这种程度？固定模式应独立于使用该模式的数据进行记录。关于手头数据的注意事项备注可以进入文件中的行符号中，但不需要编译成外部格式IMHO，因为它们仅在实际振动/编辑该数据时才需要。我知道您喜欢函数式编程，所以我不需要指出程序和数据之间的界限并不总是那么清晰。特别是，我们使用yaml文件来定义某些任务（几个任务可能使用相同的代码，但它们做的事情本质上是不同的）。比如说，YAML中的DSL。DSL需要评论。嗯，没有@delnan是对的。。。“YAML在其发展的早期，据说是指“另一种标记语言”[3]，但被重新定义以区分其面向数据的用途，而不是文档标记。”——。如果您使用YAML进行标记，即使是在DSL中，您也打破了YAML的定义…不确定我建议在哪里使用YAML进行标记？正如我所说，我们使用它作为穷人的DSL，可以说，它为我们提供了很好的服务。只需要在那里添加一些元数据。最后，我们简单地用

文档

部分扩展了模式。谢谢，这也是我们决定这样做的原因（只使用结构化元数据，而不是这里建议的单个字符串字段）。我们已经在使用它并从中生成HTML文档了。“注意：YAML通常会丢弃您的注释，因此它们对于往返元数据不是很有用”+1:-）谢谢您的想法。Ansible大量使用YAML格式，该格式不再只是数据，因为它的剧本被解释为程序。。。我正在寻找一种方法来记录它们，就像我以前用perldoc做的那样。