生成的文档是否应该进入源代码控制？ [英] Should generated documentation go into source control?

问题描述

最近（最后）我已经开始记录我的一个开源项目。该项目是.Net的类库。我使用Doxygen从源代码生成HTML文档。

现在，我的问题是应该存储Doxygen在我的源代码控件中生成的HTML文件吗？

解决方案

您是否认为每次提交代码时都可以重建文档？否则，您的文档将很快变得不可靠，因为它可能 - 或者可能与您的代码不一致。

但是我明白这是很难决定的，因为特别如果您的项目是启动/小型的，则您没有自动化构建服务器的基础架构（因此您无法在线提供同步的生成的文档），并将其留给用户意味着您迫使他们安装Doxygen。

我的解决方案（如同我的项目一样）：

• 不要将生成的文档放在版本控制下




• 只需通过启动所有目标平台即可编写生成文档的脚本（BAT for给出了源代码生成工具的Windows，Sh为* nix），提供源代码。好的主意是要求用户安装该工具（并提供URL）（如果没有安装）。




• 通过编译的二进制文件和生成的文档，即使你的程序仍处于开发的早期阶段。但如果是，请下载包的用户清楚。不要标记buggy /半完成版本1.0！用户将尝试您的程序/库，看到它是有问题的，永远不会再给它一个机会！

编辑：

我看到你在使用.NET。您是否考虑使用 Sandcastle ？它是由Microsoft专门为.NET设计的文档工具。我认为我生成比Doxygen更好的帮助文件 - 其使用的例子是整个MSDN .NET文档库：）

它的缺点是生成过程是按照比Doxygen的幅度慢。如果您仅在执行发布时执行此操作，这不是一个问题，但如果您希望在每次提交（更改API）之前生成帮助，那将是非常不切实际的。

I've been recently (finally) getting around to documenting one of my open source projects. The project is a class library for .Net. I'm using Doxygen for generating HTML documentation from the source code.

Now, my question is should I store the HTML files Doxygen produces in my source control?

解决方案

Do you think you would be able to rebuild the documentation every time you commit code? If not, then your documentation would quickly become unreliable, because it might - or might not be in sync with your code.

But I understand this is hard decision, because especially if your project is startup/small, you don't have the infrastructure for automated build server (so you can't offer synced generated documentation online), and leaving this to users means you force them to install Doxygen.

My solution (as I do it with my project):

• Don't put the generated documentation under version control

• Write scripts that generate the documentation easily just by starting them for all target platforms (BAT for Windows, Sh for *nix) given the source generation tool is installed, provide these with source codes. Good idea is to ask the users to install the tool (and provide URL) if it is not installed.

• Better do releases often than not with compiled binaries and generated documentation, even if your program is still in early stages of development. But if it is, make it clear to the users who download the package. Never label buggy/half-done version 1.0! Users would try your program/library, see it as problematic and never give it a chance again!

EDIT:

I see you are using .NET. Did you consider using Sandcastle? It is documentation tool designed by Microsoft specifically for .NET. I think i generates much better help files than Doxygen - example of its use is whole MSDN .NET documentation library :)

Its downside is that the generation process is by orders of magnitude slower than Doxygen's. It is not an issue if you do this only when doing releases, but it would be very impractical if you wanted to generate help before every commit (that changes API).

这篇关于生成的文档是否应该进入源代码控制？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！