DocFX：为多个项目生成API文档

Question

我正在处理一个解决方案中包含多个项目的项目。我想从外部目录生成文档，以保持应用程序代码文件夹的清洁。当我尝试在docfx.json中设置src目录时，它似乎不喜欢绝对路径，也不喜欢相对路径。

{
  "metadata": 
  [{
         "src": 
         [{
               "files": ["../../../Repos/Wsi.Extranet.CommonServices/Wsi.Extranet.CommonServices/**/*.csproj"]
               "exclude": 
               [
                    "**/obj/**",
                    "**/bin/**",
                    "_site/**"
               ]
        }],
        "dest": "api"
}],
"build": {
"content": [
  {
    "files": [
      "api/**.yml",
      "api/index.md"
    ]
  },
  {
    "files": [
      "articles/**.md",
      "articles/**/toc.yml",
      "toc.yml",
      "*.md"
    ],
    "exclude": [
      "obj/**",
      "_site/**"
    ]
  }
],
"resource": [
  {
    "files": [
      "images/**"
    ],
    "exclude": [
      "obj/**",
      "_site/**"
    ]
  }
],
"overwrite": [
  {
    "files": [
      "apidoc/**.md"
    ],
    "exclude": [
      "obj/**",
      "_site/**"
    ]
  }
],
"src":    "../../../Repos/Wsi.Extranet.CommonServices/Wsi.Extranet.CommonServices",
"dest": "_site",
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": [
  "default"
],
"postProcessors": [],
"noLangKeyword": false
 }
}

它说构建成功，但没有找到任何文件，并且搜索的目录仍停留在当前目录。

D:\temp\WsiApiDocs\docfx_project>docfx metadata
Info: Config file docfx.json found, start generating metadata...
Info: No files are found with glob pattern **/*.csproj, excluding
    **/obj/**,**/bin/**,_site/**, under directory "D:\temp\WsiApiDocs\docfx_project"
Info: Completed executing in 54.0087 milliseconds.


Build succeeded.
    0 Warning(s)
    0 Error(s)

当我尝试将相对路径放入文件属性中时，会出现以下错误：

D:\temp\WsiApiDocs\docfx_project>docfx metadata
Info: Config file docfx.json found, start generating metadata...
Info: No files are found with glob pattern
 ../../../Repos/Wsi.Extranet.CommonServices/Wsi.Extranet.CommonServices/**/*.csproj, 
excluding **/obj/**,**/bin/**,_site/**, under directory
 "D:\temp\WsiApiDocs\docfx_project"
**Warning: NOTE that `../` is currently not supported in glob pattern, please use `../` in `src` option instead.**
Info: Completed executing in 48.9621 milliseconds.


Build succeeded with warning.
Warning: NOTE that `../` is currently not supported in glob pattern, please use `../` in `src` option instead.
    1 Warning(s)
    0 Error(s)

所以我的困惑似乎在于如何使用src选项。如果在元数据中使用src，则似乎无法指定文件和排除信息。我尝试在与元数据相同级别上使用src属性，但似乎没有任何作用。

- Terry Palmer

Answer 1

正如错误所述

../ 目前在 glob 模式中不受支持。

files、exclude 等使用 glob 模式。请通过 src 设置基目录：

{
  "metadata": [
    {
      "src": [
        {
          "files": "Repos/Wsi.Extranet.CommonServices/Wsi.Extranet.CommonServices/**.csproj",
          "exclude": [
            "**/obj/**",
            "**/bin/**"
          ],
          "src": "../../.." // <---- base directory
        }
      ],
      "dest": "api"
    }
  ],
  "content": [
    {
      "files": [
        "api/**.yml",
        "api/index.md"
      ]
    }
    // ...
  ]
}

这里是一个多个项目结构化的示例

- Marcus S.

---

太棒了，谢谢 Marcus！我不知道为什么我一直在把它想得比实际难。当它说要通过src设置基本目录时，我以为它在谈论父src节点。甚至没有想到在父src节点中放置一个子src。你提供的关于组织多个项目的链接也非常有帮助。 - Terry Palmer

我从未见过如此令人困惑的错误信息。使用src...但是src是一个数组...不，你必须猜测src里面还有一个src。 - Cyprien Autexier

我曾经遇到过同样的问题。如果它有这种设计，很难说服我的团队中的任何人使用它。他们嘲笑了。 - zameb