在使用 Sandcastle 构建期间自动生成 html 文档 [英] Generate html documentation automatically during a build with Sandcastle

问题描述

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

What steps do I need to take to get HTML documentation automatically building via the build step in Visual Studio? I have all the comments in place and the comments.xml file being generated, and Sandcastle installed. I just need to know what to add to the post-build step in order to generate the docs.

推荐答案

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

Some changes have been made since this question was asked. Sandcastle no longer includes SandcastleBuilderConsole.exe. Instead it uses plain old MSBuild.exe.

为了将其与 Visual Studio 集成，我是这样做的:

To integrate this with visual studio here is what I did:

将其放在您的构建后事件中:

Place this in your Post-build event:

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

"$(SystemRoot)microsoft.netframework64v4.0.30319msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectNamedocDocumentationProjectName.shfbproj"

:Exit

这将导致 Visual Studio 构建您的文档，仅当您在发布"模式下构建时.这样，当您在开发过程中以调试"模式构建时，您就不会永远等待.

This will cause visual studio to build your documentation, only when you build in "Release" mode. That way you aren't waiting forever when you build in "Debug" mode during development.

一些注意事项:

• 我的系统是 64 位的，如果你的不是，那么在 msbuild.exe 的路径中用 framework 替换 framework64.

• My system is 64-bit, if yours is not then replace framework64 with framework in the path to msbuild.exe.

我设置它的方式是单独记录解决方案中的每个项目.如果您有一个包含多个项目的Sandcastle 帮助文件生成器"项目文件，那么您可能希望摆脱 ProjectName 并将 doc 移动到解决方案目录中.在这种情况下，您将只想将构建后事件命令放在解决方案中最后构建的项目上.如果您将它放在每个项目的 Post-build 事件中，那么您将为每个构建的项目重建文档.不用说，你会在那里坐一会儿.我个人更喜欢单独记录每个项目，但这只是我自己.

The way I have it setup is to document each project in my solution individually. If you have a "Sandcastle Help File Builder" project file which includes several projects together, then you probably want to get rid of ProjectName and move doc into the solution directory. In this case you will want to only put the Post-build event commands on the project that is built LAST in your solution. If you put it in the Post-build event for every project then you will be rebuilding your documentation for each project that is built. Needless to say, you'll be sitting there a while. Personally I prefer to document each project individually, but that's just me.

安装 Sandcastle 和Sandcastle 帮助文件生成器".

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

If you don't know how to get Sandcastle and "Sandcastle Help File Builder" setup correctly, then follow these steps:

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

1. Download and install Sandcastle from http://sandcastle.codeplex.com/ (if you have a 64 bit system, you will need to add an environment variable. The instructions are here.

从 http://shfb.codeplex.com/下载并安装Sandcastle 帮助文件生成器"a>(如果收到有关 MSHelp2 的警告，请忽略.您将不需要它.)

Download and install "Sandcastle Help File Builder" from http://shfb.codeplex.com/ (ignore warnings about MSHelp2 if you get any. You won't be needing it.)

安装好这些之后，就可以使用Sandcastle 帮助文件生成器"来创建一个新的文档项目.当它询问您将文件保存在何处时，请将其保存在您的解决方案/项目中的文档文件夹中.http://www.chevtek.com/Temp/NewProject.jpg

Once you have those installed then use "Sandcastle Help File Builder" to create a new documentation project. When it asks you where to save the file, save it in the documentation folder you have in your solution/project. http://www.chevtek.com/Temp/NewProject.jpg

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

After creating a new project you'll need to choose which kind of documentation you want to create. A compiled windows help file, a website, or both. http://www.chevtek.com/Temp/DocumentationType.jpg

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

If you saved the SHFB project file in the directory where you want your documentation to be generated then you can skip this step. But if you want the generated documentation to be placed elsewhere then you need to adjust the output path. http://www.chevtek.com/Temp/OutputPath.jpg NOTE: One thing to keep in mind about the output path (which frustrated me for an hour) is that when you have website checked as the type of documentation you want, it will overwrite content in its output path. What they neglect to tell you is that SHFB purposely restricted certain folders from being included as part of the output path. Desktop is one such folder. Your output path cannot be on the desktop, not even a sub-folder of desktop. It can't by My Documents either, but it CAN be a subfolder of my documents. If you get errors when building your documentation, try changing the output path and see if that fixes it. See http://shfb.codeplex.com/discussions/226668?ProjectName=shfb for details on this.

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

Finally, you will need to add a reference to the project you want to document. If you are doing individual projects like I do, then for each SHFB project file you create, you will reference the corresponding .CSPROJ file. If you have one SHFB project for your entire solution, then you would find the .SLN file for your solution. (sandcastle also works if you reference the compiled DLLs, but since you're integrating it with Visual Studio I find it makes more sense to reference the project/solution files instead. This may also mean that it really doesn't matter which project you do the post-build event on since it's referencing the code instead of the DLLs, but it's better to be safe and put it on the last project that's built) http://www.chevtek.com/Temp/AddSource.jpg

保存项目，您可以关闭Sandcastle Help File Builder".现在一切都设置好了.只需确保将文档项目文件放在生成后事件中批处理命令指向的适当文件夹中.

Save the project and you can close "Sandcastle Help File Builder". Now all is setup. Just be sure to put the documentation project file in the appropriate folder that the batch commands point to in the Post-build event.

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

I hope my short tutorial helps you out! It was very hard for me to find any decent tutorials showing me how to use sandcastle, let alone how to integrate it with visual studio. Hopefully future google searches will turn up this question.

这篇关于在使用 Sandcastle 构建期间自动生成 html 文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！