Question

我需要采取哪些步骤才能通过Visual Studio中的构建步骤自动构建HTML文档？我已经准备好所有注释并生成了comments.xml文件，并安装了Sandcastle。我只需要知道要在后期构建步骤中添加什么以生成文档。

Answer 1

自从提出这个问题以来，已经做了一些改变。沙堡不再包括SandcastleBuilderConsole.exe。相反，它使用普通的MSBuild.exe。

要将这个与visual studio整合在一起，我就是这样做的：

将其置于构建后的事件中：

IF "$(ConfigurationName)"=="Release" Goto Exit

"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"

:Exit

只有在“发布”模式下构建时，才会使visual studio构建您的文档。这样，当您在开发期间构建“调试”模式时，您不会永远等待。

一对夫妇注意到：

我的系统是64位，如果您的系统不是，请在framework64的路径中将framework替换为msbuild.exe。
我设置它的方法是单独记录我的解决方案中的每个项目。如果您有一个“Sandcastle帮助文件生成器”项目文件，其中包含多个项目，那么您可能希望摆脱ProjectName\并将doc移动到解决方案目录中。在这种情况下，您只希望将Post-build事件命令放在解决方案中最后构建的项目中。如果将它放在每个项目的Post-build事件中，那么您将为每个构建的项目重建文档。不用说，你会在那里坐一会儿。我个人更喜欢单独记录每个项目，但那只是我。

安装Sandcastle和“Sandcastle帮助文件生成器”。

如果您不知道如何正确设置Sandcastle和“Sandcastle帮助文件生成器”，请按照以下步骤操作：

从http://sandcastle.codeplex.com/下载并安装Sandcastle（如果您有64位系统，则需要添加一个环境变量。说明为here。
从http://shfb.codeplex.com/下载并安装“Sandcastle帮助文件生成器”（如果您有任何问题，请忽略有关MSHelp2的警告。您将不需要它。）
安装完成后，使用“Sandcastle帮助文件生成器”创建新的文档项目。当它询问您保存文件的位置时，请将其保存在解决方案/项目中的文档文件夹中。 http://www.chevtek.com/Temp/NewProject.jpg
创建新项目后，您需要选择要创建的文档类型。已编译的Windows帮助文件，网站或两者。 http://www.chevtek.com/Temp/DocumentationType.jpg
如果您将SHFB项目文件保存在要生成文档的目录中，则可以跳过此步骤。但是，如果您希望将生成的文档放在其他位置，则需要调整输出路径。 http://www.chevtek.com/Temp/OutputPath.jpg 注意：关于输出路径（让我感到沮丧一小时）要记住的一件事是，当您将网站检查为所需的文档类型时，它将覆盖其输出路径中的内容。他们忽略了告诉你的是，SHFB故意限制某些文件夹被包含在输出路径的一部分中。桌面是一个这样的文件夹。您的输出路径不能在桌面上，甚至不能在桌面的子文件夹中。它不能通过我的文档，但它可以是我的文档的子文件夹。如果在构建文档时遇到错误，请尝试更改输出路径并查看是否可以修复它。有关详细信息，请参阅http://shfb.codeplex.com/discussions/226668?ProjectName=shfb。
最后，您需要添加对要记录的项目的引用。如果你正在做我喜欢的单个项目，那么对于你创建的每个SHFB项目文件，你将引用相应的.CSPROJ文件。如果您的整个解决方案有一个SHFB项目，那么您将找到适合您的解决方案的.SLN文件。（如果您引用已编译的DLL，sandcastle也可以工作，但由于您将它与Visual Studio集成，我发现引用项目/解决方案文件更有意义。这也可能意味着您在哪个项目中无关紧要做后期构建事件，因为它引用代码而不是DLL，但最好是安全并将它放在最后构建的项目上 http://www.chevtek.com/Temp/AddSource.jpg
保存项目，您可以关闭“Sandcastle帮助文件生成器”。现在一切都安装好了。只需确保将文档项目文件放在批处理命令指向构建后事件的相应文件夹中。

我希望我的简短教程能帮到你！我很难找到任何体面的教程向我展示如何使用sandcastle，更不用说如何将它与visual studio集成。希望未来的谷歌搜索能够提出这个问题。

Answer 2

我建议您从Codeplex安装Sandcastle帮助文件生成器。

您可以从命令行运行此操作，例如来自Post-Build活动。最简单的命令行是：

<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle非常慢，所以我只为Release Builds运行它。为此，请使用以下命令创建Post-Build事件，该命令将配置名称传递给批处理文件：

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)

然后在批处理文件中，您可以测试第一个参数是否为“Release”，如果是，则运行SandcastleBuilderConsole.exe。

Answer 3

如上所述，一种简单的方法是使用Sandcastle帮助文件生成器。从命令行对构建过程进行了一些更改，现在可以使用MSbuild而不是SandcastleBuilderConsole.exe构建这些项目。所以你要做的就是：

MSbuild.exe ProjectName.shfb

Answer 4

我必须承认，我发现当前版本的Sandcastle有点缺乏;对于大型项目而言，它很慢，并且不易整合（因为它还处于早期阶段）。

对于常规使用，我实际上发现将反射器指向包含dll和xml文件的文件夹更容易 - IIRC，它将在您导航时加载xml文件。

另外，我几乎总是打开反射器......

[edit]选中，是 - 在反汇编程序面板中显示xml注释

Answer 5

安装这些：

NDoc：http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi?download

HTML Help Workshop：http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

然后使用NDocConsole.exe命令行以MSDN或CHM格式生成文档：

@c：\ progra~1 \ NDoc \ NDocConsole.exe MyCode.dll，MyCode.xml -Documenter = MSDN-CHM

我自己已经为此制作了一个外部工具，并给了它一个快捷方式，但正如之前的海报所说，你可以将它连接到一个后期制作事件，然后你就去了。

（PS我已经使用了上面的设置几年了，我对它非常满意）

在使用Sandcastle构建期间自动生成html文档

5 个答案: