我可以从 XML 文档生成 .MD 文件吗？

Question

我最近使用 Sandcastle 来记录我的类库。但是，我最近发现 Sandcastle 不再由 Microsoft 开发：https : //archive.codeplex.com/? p=sandcastle 。

我在 GitHub 上在线查看过，我发现这些天很多开源项目都使用 .MD (MarkDown) 文件。我看到 .MD 文件受 GitHub 和 TFS 支持。如何从 XML 文档文件生成 .MD 文件？

我花了最后几个小时在谷歌上搜索这个。例如，我只下载了几百次就发现了这个：https : //github.com/lijunle/Vsxmd/tree/master/Vsxmd 我不是在寻求工具推荐。我在问是否可以将 .XML 文档转换为 .MD 文件。

Answer 1

在我的场景中，我想要GitHub Wiki中的项目代码文档，并且它需要 markdown 文件而不是 html。

Visual Studio（在我的例子中是 Mac）有一个project options > build > compiler复选框可以为项目 生成 xml 文档文件。Vsxmd从这一 xml 文件生成一个 md 文件。在大多数 Markdown 预览器中查看它时，它的布局非常好且广泛，但 GitHub 似乎超时时间很短，并且无法呈现大型 Markdown 页面。

它也没有布局，但我发现 GitHub 可以呈现的是由 Web 工具vsdoc-2-md生成的单个 md 文件。

我最终在项目中使用的是Default Documentation。它是一个像Vsxmd一样在构建期间运行的 nuget ，但会生成多个md 文件，这些文件足够小，以至于 GitHub 不会抱怨。

请注意，GitHub Wiki会重命名其 URL 中的文件，以便.md删除所有扩展名。我必须进行搜索/替换以删除.md所有链接，以便单击GitHub Wiki中的文档才能正常工作。

Answer 2

对的，这是可能的。

有许多项目可以这样做。例如，您找到了Vsxmd，但也有更简单的，例如lontivero/593fc51f1208555112e0。

该过程基本上是读取每个 XML 元素（或其中一些）并将其转换为 Markdown 中的等效元素。等效项是您在编写转换器时必须选择的内容，这取决于您想要的结果文件的样式。

处理标签时事情会变得复杂，例如<inheritdoc/>您不想只打印“从父级继承”。像 Vsxmd 那样或像 lontivero 那样忽略它。

我仍在寻找更好的工具或改进工具的时间。

Answer 3

当然，可以从 XML 注释生成 Markdown。显而易见的问题是：为什么？最好的答案是：从 Markdown 内容生成一个网站。

DocFX本质上是 Sandcastle 的替代品。我使用它从 C# 代码中的 XML 注释生成文档网站。