如何在DocFX中添加.NET命名空间信息

Question

标题已经说明了一切...

在 Sandcastle 帮助文件生成器中，我们添加了 NamespaceDoc 类到每个命名空间中，以创建命名空间文档。

如何使用 DocFX 实现相同的功能？

- AxD

Answer 1

我是这样做的：

1. 在您的文档项目的根文件夹中添加一个名为namespaces的文件夹。
2. 更新您的docfx.json文件，以包含添加到namespaces文件夹的标记文件。您需要更新build部分中的overwrite属性。它将类似于下面的内容：

    "overwrite": [
      {
        "files": [
          "apidoc/**.md",
          "namespaces/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],

3. 在namespaces文件夹中为每个要添加文档的命名空间创建一个Markdown文件。最好将这些文件与命名空间同名。

   文件应该具有一个YAML头，其UID与命名空间的名称匹配。 summary：*content行告诉docfx用此文件的内容覆盖 命名空间的摘要。

   页面的其余部分是标准Markdown，将成为命名空间的摘要。 例如：

   ---
   uid：My.Groovy.Namespace
   摘要：*content
   ---
   My.Groovy.Namespace命名空间包含一堆类和接口。

- Doug Clutter

Answer 2

在源代码中没有直接添加它的方法。您可以使用覆盖文件为命名空间类型添加摘要。

- Yuby

Answer 3

我可能对这个问题非常晚，但我面临了类似的问题，我找到的解决方案涉及修改docfx源代码并添加帮助类，就像Sandcastle的解决方案一样。

免责声明：

我不声称我展示的解决方案在程序上是稳定的、安全的或者甚至是正确的。我不声称这个解决方案将在任何情况下或任何用途中都有效。我只验证，对于我来说，它完美地工作了，尽管我认识到它只是一个快速的解决方法。

步骤：

1. 我从他们的github的releases页面下载了docfx的源代码（截至今天为止是2.59.2）

---

提取解决方案后，我打开了文件 docfx-2.59.2\src\Microsoft.DocAsCode.Metadata.ManagedReference\ExtractMetadataWorker.cs。

---

这个文件中实现的类包含一个名为GetMetadataFromProjectLevelCache的方法，该方法在某个时刻从树形式中提取引用项目中的元数据。

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key); // THIS line
   // [...]
}

---

在这行之后，我添加了以下包含一个我必须实现的方法的行。

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key);
   ExtractNamespaceDocumentation(projectMetadata); // THIS line
   // [...]
}

---

实施步骤如下：

private void ExtractNamespaceDocumentation(MetadataItem node)
{
    // Terminal nodes are not of our interest in any case
    // Even if it's a namespace, it does not contain documentation
    if (node.Items is not { Count: > 0 }) return;
    
    // If it is namespace
    if (node.Type == MemberType.Namespace)
    {
        // Get (if any), the child that is class and is named "_NamespaceDoc"
        var doc = node.Items.FirstOrDefault(x =>
            x.Type == MemberType.Class && x.Name.Split('.').Last() == "_NamespaceDoc");

        // If we didn't found such class, the namespace does not contain documentation.
        // Leave and don't go further.
        if (doc is null) return;

        // Else, assign the class' Summary and remarks to the Namespace and remove the class from the tree.
        node.Summary = doc.Summary;
        node.Remarks = doc.Remarks;
        node.Items.Remove(doc);

        // job finished for this namespace, we do not want to go further down the tree.
        return;
    }

    // For non-namespace intermediate nodes (IE assembly nodes), visit the children.
    foreach (var child in node.Items) ExtractNamespaceDocumentation(child);
}

---

最后，我编译了解决方案，并使用位于 docfx-2.59.2\src\docfx\bin\Debug\net472 的新创建的 docfx.exe，成功检测到所有名为 _NamespaceDoc 的类，并使用它们的 <summary> 标签填充它们所在的命名空间。

---

记录一下，我决定在项目的根目录下创建一个新的.cs文件来包含所有_NamespaceDoc类，这样当我想要发布项目时就更容易禁用整个文件。这个文件看起来像这样：

namespace RootNamespace
{
    /// <summary>
    /// Documentation for the Root Namespace
    /// </summary>
    public static class _NamespaceDoc { }
}

namespace RootNamespace.SubFolder
{
    /// <summary>
    /// Documentation for the Root Namespace's `SubFolder` Sub-Namespace.
    /// </summary>
    public static class _NamespaceDoc { }
}

// [...]

希望这可以帮助其他正在寻找此类解决方案的人，甚至是docfx的开发人员和贡献者更可靠地实现此功能。

---

更新：

关于这种方法的更多信息，我已经在docfx的github仓库上开始了讨论。

- Andreas M.

---

哇！你会考虑从这个分支创建一个拉取请求到代码库吗？ - AxD

我已经在docfx的github仓库上开始了一次讨论，但似乎所有的开发都集中在发布/修复V3，而不是为当前稳定版本添加功能。 - Andreas M.