logo标签列表

使用Sandcastle在构建过程中自动生成HTML文档

c#visual-studio-2008documentationsandcastle
21

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

当然我不知道你的目标构建时间，但是我想提醒一下，Sandcastle 真的不适合包含在你的常规构建-调试周期中。 - Boris Callens
不，正如我在这个答案中提到的一样（https://dev59.com/5HVC5IYBdhLWcg3wsTVi），我有一个单独用于文档生成的构建过程。 - Mark Ingram
5个回答
33
自从这个问题被问出来以后，已经进行了一些更改。Sandcastle不再包括SandcastleBuilderConsole.exe。相反，它使用普通的MSBuild.exe。
要将其与Visual Studio集成，我所做的是：
将此内容放置在您的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在“Release”模式下构建文档。这样，在开发期间在“Debug”模式下构建时，您不必等待太久。

几个注意事项：

  • 我的系统是64位的，如果您的不是，则在到msbuild.exe的路径中用framework替换framework64。

  • 我设置的方式是单独为解决方案中的每个项目记录文档。如果您有一个“Sandcastle Help File Builder”项目文件，其中包括多个项目，则可能需要摆脱ProjectName\，并将doc移动到解决方案目录中。在这种情况下，您将只想在您的解决方案中最后一个构建的项目上放置Post-build事件命令。如果您将其放在每个项目的Post-build事件中，则将为构建的每个项目重新构建文档。不用说，您将坐在那里一段时间。个人而言，我更喜欢单独记录每个项目的文档，但这只是我个人的偏好。

安装Sandcastle和“Sandcastle Help File Builder”。

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

  1. 从http://sandcastle.codeplex.com/下载并安装Sandcastle（如果您有64位系统，则需要添加环境变量。请参阅here中的说明）。

  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故意限制了某些文件夹不包括在输出路径中。桌面就是这样一个文件夹。您的输出路径不能在桌面上，甚至不能是桌面的子文件夹。它也不能是“我的文档”，但它可以是“我的文档”的子文件夹。如果构建文档时出现错误，请尝试更改输出路径并查看是否可以解决问题。有关详细信息，请参见http://shfb.codeplex.com/discussions/226668?ProjectName=shfb。

  6. 最后，您需要添加对要文档化的项目的引用。如果您像我一样单独进行项目，则对于每个SHFB项目文件，您将引用相应的.CSPROJ文件。如果您为整个解决方案创建了一个SHFB项目，则您将找到解决方案的.SLN文件。（Sandcastle也适用于引用已编译的DLL，但由于您正在将其与Visual Studio集成，因此我发现引用项目/解决方案文件更有意义。这也可能意味着实际上无论您在哪个项目上执行后期构建事件都无所谓，因为它正在引用代码而不是DLL，但最好安全起见并将其放在最后一个构建的项目上） http://www.chevtek.com/Temp/AddSource.jpg

  7. 保存项目，您可以关闭“Sandcastle Help File Builder”。现在所有都设置好了。只需确保将文档项目文件放在批处理命令指向的适当文件夹中即可进行后期构建事件。

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

6
我建议你从Codeplex安装Sandcastle帮助文件生成器。你可以通过命令行运行它，例如从Post-Build事件。最简单的命令行是：
<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle非常缓慢，因此我只在发布版本构建时运行它。为此，请创建一个后期生成事件，并添加以下命令（将配置名称传递给批处理文件）：

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

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

我已经在构建后脚本中完成了这个操作，我只是检查配置名称以确保它是“Documentation”（我有3个配置，调试、发布和文档）。 - Mark Ingram
更好的是，这意味着您可以快速创建无需文档的发布版本。 - Joe
1
一个简单的方法是使用Sandcastle Help File Builder，如上所建议。 从命令行进行构建过程已经进行了一些更改，现在这些项目可以使用MSbuild而不是SandcastleBuilderConsole.exe进行构建。所以你所要做的就是： MSbuild.exe ProjectName.shfb
0

我必须承认，我觉得当前版本的Sandcastle有点不足；对于大型项目来说，它相当慢，并且不容易集成（因为它仍处于早期阶段）。

对于常规使用，我实际上发现只需将反编译器指向包含dll和xml文件的文件夹更容易 - 如果我没记错的话，当您在其中浏览时，它会加载xml文件。

此外，我几乎总是打开反编译器...

[编辑] 检查过了，是的 - xml注释显示在反汇编面板中

1
我想生成HTML文档，以便将其放在我们的内部开发网站上。 - Mark Ingram
随你喜欢。我认为 Sandcastle 的主要用途是与 ISV 合作；对于内部使用，我很高兴能够以一种可导航的方式查看注释，而不需要使用 VS……反编译器可以提供这个功能。;-p - Marc Gravell
看起来设置起来相当麻烦，所以很可能会被抛弃。 - Mark Ingram
0

安装以下内容：

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

我自己为此制作了一个外部工具并设置了快捷方式，但正如前面的帖子所说，您可以将其连接到 postbuild 事件中。

（PS：我已经使用上述设置几年了，并且非常满意）

2
NDoc不完全支持.NET 2.0，我将使用该工具与.NET 3.5 / Silverlight（这就是为什么原始问题中提到了"sandcastle"的原因）。 - Mark Ingram
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接