docFX - 在API参考目录中删除命名空间前缀

Question

我正在从C#项目中生成API参考文档。 该项目是一个大型解决方案的一部分，并且程序集和命名空间采用了长名称约定，因此项目中的每个命名空间都类似于[CompanyName]。[System]。[Area]。[Module]。[...]（例如，MyBiz.CRM.Sales.Analytics.Persistence.Common和MyBiz.CRM.Sales.Analytics.Persistence.Sql）。 由于项目中的所有命名空间都以MyBiz.CRM.Sales.开头，因此我想将左侧的TOC中的MyBiz.CRM.Sales.排除在外，在标题/页眉中提到它即可，同时为每个系统和区域生成参考文档。 这在docFX中是否可能？还是需要编写自定义的服务器端后构建事件脚本？ 谢谢您的帮助。

- Alex Michel

Answer 1

我也遇到了相同的问题，并通过编写模板解决了它。模板唯一做的事情就是覆盖了需要在名为 toc.extension.js 的文件中指定的 preTransform 钩子，我在那里去除了长命名空间前缀。由于我的目录有多层，所以我进行了递归处理。你可以很可能将其硬编码为你需要的级别。我的代码如下所示：

exports.preTransform = function (model) {
  // replace recursively the root namespace by ""
  transformItem(model, 1);
  return model;

  function transformItem(item, level) {
    if (item.name) {
      item.name = item.name.replace("Some.Very.Long.Namespace.Prefix.", '');
    } else {
      item.name = null;
    }

    if (item.items && item.items.length > 0) {
      var length = item.items.length;
      for (var i = 0; i < length; i++) {
        transformItem(item.items[i], level + 1);
      };
    }
  }
}

接下来，我只需在 docfx.json 中指定自己的模板，同时保留默认模板，这将导致钩子被调用。具体操作如下：

"build": {
    "template": [
        "default",
        "/path/to/your/template/folder"
    ]
}

参考文献：Docfx: 如何创建自定义模板

- scriptator

Answer 2

在 DocFX 2.65 中，您可以在 docfx.json 的元数据部分中设置 namespaceLayout 属性，并使用以下属性：

- flattened：TOC 中的命名空间节点是列表。 - nested：TOC 中的命名空间节点是嵌套的。

Reference: https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#customization-options

- Gustavo Mauricio De Barros