我可以从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

当然可以从XML注释中生成markdown。显而易见的问题是：为什么？最佳答案是：从降价内容生成网站。

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

Answer 2

是的，有可能。

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

该过程基本上是读取每个XML元素（或其中的一些）并将其转换为markdown中的等效元素。等效文件是编写转换器时必须选择的内容，具体取决于生成文件所需的样式。

如果您不想仅打印“从父项继承”，则处理<inheritdoc/>之类的标记时，事情会变得很复杂。就像Vsxmd一样，或者像lontivero一样忽略它。

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

Answer 3

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

Visual Studio（在我的情况下为Mac）的项目有一个generate the xml documentation file的project options > build > compiler复选框。 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处单击文档以进行工作。