如何让 dartdoc 包含附加文档？

Question

我想了解是否有办法在由

dartdoc

生成的 API 文档中包含其他文档。

根据包布局约定，

getting_started.md

目录中包含一个

doc/

文件，并显示如下...

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

该文件如何通过

dartdoc

合并到文档中以及它在输出中显示在哪里？我尝试简单地在

*.md

目录中添加我自己的

doc/

文件，但它们似乎没有被使用。

我还在 dartdoc documentation 中阅读了有关 Categories 的内容，其中指出：

类别：每个类别/主题的更多详细信息。对于您想要记录的主题，请使用 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

Dartdoc 不允许 API 文档中包含任意 .md 文件。您可以在 README.md 或其他文档中创建指向它们的链接，例如通过 GitHub 或其他为他们提供服务的网址。

例如，dartdoc 包为“贡献”文档执行此操作，并且它显示在 API 文档中，如下所示：https://pub.dev/documentation/dartdoc/3.0.0/index.html

仅当源代码中至少有一个元素被声明为该类别的成员时，类别才会呈现，因此该功能不太适合此用例。

Answer 2

我不同意 - 任意 .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 文件。