课程文档建议

Question

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

我希望为每个项目生成MSDN样式的HTML文档，并将其部署到一个所有开发人员都可以轻松访问的集中位置。我还希望自动化这些步骤，以便它们可以定期运行，因此我和其他开发人员无需担心在进行更改时记住生成和部署新文档。我看过Sandcastle和Doxygen，它们看起来都是生成我想要的文档的好选择，但我需要一个好的方法来自动生成它的建议，比如夜间工作或其他什么。

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

编辑：

我很欣赏所有好主意。现在我可以调查一些路线了，但是直到弄脏我才知道哪条路线效果最好。 Sandcastle帮助文件生成器似乎为我提供了我想要做的最佳选择，所以我会对这个建议表示赞同。但是，如果我有更多时间研究XSLT和CSS解决方案以使XML数据看起来恰到好处，那么我首先会追求这个建议。

再次感谢大家！

Answer 1

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

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

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

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

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

Answer 2

看看Sandcastle Help File Builder。这使用独立项目，因此您可以根据需要随时构建它们（例如，每次检查更改时，每晚或作为continuous integration系统的一部分）。

Answer 3

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

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