如何让 dartdoc 包含其他文档？

Question

我想了解是否有办法在由dartdoc.

根据包布局约定getting_started.md，doc/目录中包含一个文件，显示如下...

enchilada/
  ...
  doc/
    api/ ***
    getting_started.md

该文件如何合并到文档中dartdoc以及它在输出中的何处显示？我试图简单地*.md在doc/目录中添加我自己的文件，但它们似乎没有被使用。

我还在dartdoc文档中阅读了关于类别的内容，其中指出：

类别：为每个类别/题目的更多细节。对于您想要记录的主题，使用 markdown: 指定 markdown 文件以用于类别页面。或者，将源代码中的类别重命名为带有“name:”的显示名称。如果 dartdoc_options.yaml 中没有定义匹配的类别，则源代码中声明的类别将不可见。

所以我然后尝试dartdoc_options.yaml像这样引用文件中的其他文档......

dartdoc:
  categories: 
    "Getting Started":
      markdown: doc/getting_started.md

    "Search Filters":
      markdown: doc/search_filters.md


  categoryOrder: ["Getting Started", "Search Filters"]

但这也没有产生任何结果。

有谁知道是否可以包含其他文档以及如何完成此操作？

Answer 1

我不同意 - 任意 .md 得到了很好的满足，我使用 md 文件作为我需要记录的每个库的顶级解释器。

但也有一些“陷阱”，正如其他人指出的那样：

1. 您的方法/函数文档字符串应包含您想要的主题类别的 @category 语句
2. 您的 options.yaml 应包含类别及其顺序
3. 您需要文档字符串中的类别和 .yaml 中的匹配引用，否则其中一个将被忽略
4. 你需要一个匹配的 .md 文件（我将我的文件放在 docs 文件夹中）

然后你的 yaml 中将会有类似这样的内容：

dartdoc:
  categories:
    "Getting Started":
      markdown: docs/install.md
      name: install
    "Authorization":
      markdown: docs/auth.md
      name: authorization
    
  categoryOrder: ["Getting Started", "Authorization"]

你的方法/函数将有这个文档字符串：

/// {@category Authorization}

不要忘记也创建 .md 文件。