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

StackOverflow https://stackoverflow.com/questions/211693

题

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

有帮助吗？

解决方案

自从提出这个问题以来，已经进行了一些更改。沙堡不再包括 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 Help File Builder”项目文件，其中包含多个项目，那么您可能想要摆脱 ProjectName\ 并移动 doc 进入解决方案目录。在这种情况下，您只想将构建后事件命令放在解决方案中最后构建的项目上。如果您将其放入每个项目的构建后事件中，那么您将为每个构建的项目重建文档。不用说，你会在那里坐一会儿。就我个人而言，我更喜欢单独记录每个项目，但这只是我个人的想法。

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

如果您不知道如何正确安装 Sandcastle 和“Sandcastle Help File Builder”，请按照以下步骤操作：

  1. 从以下位置下载并安装 Sandcastle http://sandcastle.codeplex.com/ （如果您有64位系统，则需要添加环境变量。说明是 这里.

  2. 下载并安装“Sandcastle 帮助文件生成器”： http://shfb.codeplex.com/ （如果收到有关 MSHelp2 的警告，请忽略。你不会需要它。）

  3. 安装完这些后，请使用“Sandcastle Help File Builder”创建一个新的文档项目。当它询问您保存文件的位置时，请将其保存在解决方案/项目中的文档文件夹中。http://www.chevtek.com/Temp/NewProject.jpg

  4. 创建新项目后，您需要选择要创建的文档类型。已编译的 Windows 帮助文件、网站或两者。http://www.chevtek.com/Temp/DocumentationType.jpg

  5. 如果您将 SHFB 项目文件保存在要生成文档的目录中，则可以跳过此步骤。但如果您希望将生成的文档放置在其他地方，那么您需要调整输出路径。http://www.chevtek.com/Temp/OutputPath.jpg笔记：关于输出路径需要记住的一件事（这让我沮丧了一个小时）是，当您将网站检查为所需的文档类型时，它将覆盖其输出路径中的内容。他们没有告诉您的是 SHFB 故意限制某些文件夹作为输出路径的一部分。Desktop 就是这样的文件夹之一。你的输出路径不能在桌面上，甚至不能是桌面的子文件夹。它也不能是我的文档，但它可以是我的文档的子文件夹。如果您在构建文档时遇到错误，请尝试更改输出路径并查看是否可以解决问题。看 http://shfb.codeplex.com/discussions/226668?ProjectName=shfb 有关详细信息。

  6. 最后，您需要添加对要记录的项目的引用。如果您像我一样执行单个项目，那么对于您创建的每个 SHFB 项目文件，您将引用相应的 .CSPROJ 文件。如果您的整个解决方案有一个 SHFB 项目，那么您将找到适合您的解决方案的 .SLN 文件。（如果您引用已编译的 DLL，sandcastle 也可以工作，但由于您将其与 Visual Studio 集成，我发现引用项目/解决方案文件更有意义。这也可能意味着您在哪个项目上执行构建后事件并不重要，因为它引用的是代码而不是 DLL，但为了安全起见，最好将其放在最后构建的项目上）http://www.chevtek.com/Temp/AddSource.jpg

  7. 保存项目，您可以关闭“Sandcastle Help File Builder”。现在一切都已设置完毕。只需确保将文档项目文件放入批处理命令在构建后事件中指向的适当文件夹中即可。

我希望我的简短教程对您有所帮助！对我来说，很难找到任何像样的教程来展示如何使用 sandcastle，更不用说如何将它与 Visual Studio 集成了。希望未来的谷歌搜索会出现这个问题。

其他提示

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

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

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

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

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

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

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

MSbuild.exe ProjectName.shfb

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

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

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

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

安装这些：

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

HTML帮助研讨会： 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我已经使用了上面的设置几年了，我对它非常满意）

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top