与沙堡在构建过程中自动生成HTML文档 [英] Generate html documentation automatically during a build with Sandcastle
问题描述
哪些步骤，我需要采取自动获取HTML文档通过在Visual Studio中构建步骤构建？我正在生成全部到位的意见和comments.xml文件，并安装沙堡。我只需要知道如何添加，以便生成文档的生成后步骤。
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.
推荐答案
一些修改提出因为这个问题被问。沙塔不再包括 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:
把这个在生成后事件：
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来构建你的文档，只有当你在释放模式建设。 。这样，当你在开发过程中的调试模式打造你不会永远等待
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位的，如果你不能再更换
framework64与框架中的路径msbuild.exe。
我把它设置的方式是单独记录在我的解决方案的每个项目。如果你有一个沙堡帮助文件生成器的项目文件，其中包括几个项目一起，那么你可能想摆脱 ProjectName\ 中移动 DOC 到解决方案目录中。在这种情况下，你会希望只把一个内置上次在解决方案中的项目生成后事件命令。如果你把它在生成后事件的每一个项目，那么你将重建你的文档是内置的每个项目。不用说，你会坐在那里一段时间。我个人更喜欢单独记录每一个项目，但是这只是我。
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.
安装沙堡，并沙堡帮助文件生成器
如果你不知道如何让沙堡，并沙堡帮助正确文件生成器的设置，然后按照下列步骤：
If you don't know how to get Sandcastle and "Sandcastle Help File Builder" setup correctly, then follow these steps:
-
下载，然后从 HTTP安装沙堡：//沙塔.codeplex.com / （如果你有一个64位系统，你将需要添加的环境变量。该指令的这里
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/ （如果你得到任何忽略有关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.)
一旦你已经安装了这些，然后使用沙堡帮助文件生成器来创建一个新的文件项目。当它要求你在哪里保存文件，将它保存在您的解决方案/项目有文档文件夹中。
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.
创建一个新项目后，你需要选择要创建哪种文件。编译的Windows帮助文件，网站，或两者兼而有之。
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.
如果您保存SHFB在你想生成你的文档，那么你可以跳过这一步的目录中的项目文件。但是如果你想生成的文档放在别的地方，那么你需要调整输出路径。
注：有一点要牢记有关的输出路径（这我感到沮丧了一个小时）是当你有网站核对，只要你想的文档类型，它将覆盖在它的输出路径的内容。他们忽略了告诉你那是什么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. 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沙塔也适用，但因为你是与Visual Studio集成在一起，我觉得它更有意义的参考项目/解决方案文件来代替。这也可能意味着它真的并不重要项目，你做，因为它的引用代码，而不是DLL文件的生成后事件，但最好是安全的，并把它放在那的建成）
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)
保存项目，你可以关闭沙堡帮助文件生成器。现在，所有的设置。只是一定要放在文档的项目文件中的批处理命令指向生成后事件中的相应文件夹。
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.
我希望我的简短的教程可以帮助你！这是我很难找到任何像样的教程向我展示了如何使用沙塔，更不用说如何将它与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.
这篇关于与沙堡在构建过程中自动生成HTML文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
