21

我需要采取哪些步骤才能通过 Visual Studio 中的构建步骤自动构建 HTML 文档？我有所有的评论和正在生成的 comments.xml 文件，并安装了 Sandcastle。我只需要知道要在构建后步骤中添加什么来生成文档。

4

5 回答 5

33

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

要将其与视觉工作室集成，这是我所做的：

把它放在你的 Post-build 事件中：

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 构建您的文档。这样，当您在开发过程中以“调试”模式构建时，您就不会永远等待。

几点注意事项：

  • framework64我的系统是 64 位的，如果你的不是，那么framework在msbuild.exe.

  • 我设置它的方式是分别记录我的解决方案中的每个项目。如果您有一个包含多个项目的“Sandcastle Help File Builder”项目文件，那么您可能希望摆脱ProjectName\并doc进入解决方案目录。在这种情况下，您只想将构建后事件命令放在解决方案中最后构建的项目上。如果您将它放在每个项目的 Post-build 事件中，那么您将为每个已构建的项目重新构建文档。不用说，你会在那里坐一会儿。就我个人而言，我更喜欢单独记录每个项目，但这只是我自己。

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

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

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

  2. 从http://shfb.codeplex.com/下载并安装“Sandcastle Help File Builder” （如果有任何关于 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”。现在一切都设置好了。只需确保将文档项目文件放在批处理命令在 Post-build 事件中指向的适当文件夹中。

希望我的简短教程能帮到你！我很难找到任何像样的教程来教我如何使用沙堡，更不用说如何将它与 Visual Studio 集成了。希望未来的谷歌搜索会出现这个问题。

于 2011-03-05T00:43:29.567 回答
6

我建议您从Codeplex安装 Sandcastle Help File Builder 。

您可以从命令行运行它，例如从 Post-Build 事件。最简单的命令行是：

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

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

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

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

于 2008-10-17T10:51:16.107 回答
1

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

MSbuild.exe 项目名称.shfb

于 2011-01-20T16:59:15.680 回答
0

我必须承认，我发现当前版本的 Sandcastle 有点欠缺。对于大型项目，它很慢，并且不容易集成（因为它还为时过早）。

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

另外，无论如何，我几乎总是打开反光板...

[编辑] 选中，是的 - 反汇编器面板中显示 xml 注释

于 2008-10-17T10:54:29.127 回答
0

安装这些：

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 我已经使用上面的设置好几年了，很满意）

于 2008-10-17T11:09:59.890 回答