类文档建议

Question

我们是一家微软商店，专注于使用C＃。我们有几个项目，包括网站，Windows服务和类库，都包含了XML注释。

我正在寻找为每个项目生成MSDN风格的HTML文档，并将其部署到所有开发人员都可以轻松访问的集中位置。我也希望自动执行这些步骤，以便它们能够定期运行，这样，我和其他开发人员就不必担心在进行更改时记住生成和部署新文档。我已经看过Sandcastle和Doxygen，并且都希望能够生成我想要的文档，但我需要一个很好的方法来自动生成它，例如在夜间工作或其他方面。

有人在那里做这样的事情吗？我不是最终的结果是HTML出售;特别是如果有更好的主意。

编辑：

我欣赏所有的好主意。现在我可以调查一些路线，但我不知道哪个路线最好，直到我弄脏手。 Sandcastle的帮助文件生成器似乎为我提供了最好的选择，所以我会点头示意这个建议。但是，如果我有更多时间来处理XSLT和CSS解决方案以使XML数据看起来恰到好处，那么我会首先寻求这一建议。

再次感谢大家！

Answer 1

看看Sandcastle Help File Builder。这使用了独立的项目，因此您可以随时随地创建它们（例如每晚或每次检入更改时都将其作为您的系统的一部分）。

Answer 2

我这样做与我们的项目。基本上我们使用doxywizard来设置配置Doxyfile，它将设置生成的html的规范。然后，在构建服务器的步骤中，我调用“doxygen doxyfile”。

我们的Doxyfile被配置为在我们的网络服务器可见的区域生成doxygen文件。因此，每次提交到主干都会导致文档自动重建。

Answer 3

您不需要任何第三方工具来生成漂亮的文档：C＃编译器可以从XML中输出XML注释文档，您只需要设计一个漂亮的CSS以在浏览器中显示它。如果您不满意，也可以在应用CSS之前生成自己的XSLT转换，as described here（在注释中查找CSS的示例！）。

或者，您可以使用此XML文档并使用诸如NDoc之类的东西对其进行改进。这是一个nice article关于如何做到这一点，遗憾的是有些过时。

通过运行带编号/doc:documentationfilename.xml参数的编译器，您可以只手动将项目的文档构建到单个XML文件中。

您也可以在Visual Studio中（项目属性 - >文档）指示将此选项添加到项目的每个版本，以便每次构建项目时都会生成XML文件。然后，您可以挂接生成后事件以将XML文件复制到存储库。

您也可以在您的Team Foundation Server上设置MS Build以构建文档并以类似的方式将其复制到存储库（/p:DocumentationFile=fileName.xml）;