在与Sandcastle建立过程中自动生成html文档 [英] Generate html documentation automatically during a build with Sandcastle

问题描述

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

解决方案

有些更改已被自提出这个问题以来。沙堡不再包含 SandcastleBuilderConsole.exe 。而是使用纯旧的 MSBuild.exe 。

要将这个视觉工作室整合到这里就是我所做的： / p>

将其放在您的后期制作活动中：

  IF$ （ConfigurationName）==ReleaseGoto Exit 
 
$（SystemRoot）\microsoft.net\framework64\v4.0.30319\msbuild.exe/ p：CleanIntermediates = True / p：Configuration = Release$（SolutionDir）ProjectName\doc\DocumentationProjectName.shfbproj
 
：退出
  

只有当您建立发布模式时，这将导致可视化工作室构建您的文档。这样你就不会在开发过程中建立调试模式时永远等待。

一对情侣注释：

• 我的系统是64位，如果你的代码没有被替换为 framework64 与 framework 在 msbuild.exe 的路径中。




• 是单独记录我的解决方案中的每个项目。如果您有一个Sandcastle帮助文件生成器项目文件，其中包含几个项目，那么您可能想要摆脱 ProjectName\ 并移动 doc 进入解决方案目录。在这种情况下，您只需要将Post-build事件命令放在您的解决方案中构建的项目中。如果您将其放在每个项目的后期构建事件中，那么您将为每个项目重建您的文档。不用说，你会坐在那里一会儿。个人而言，我宁愿单独记录每个项目，但这只是我。

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

如果您不知道如何正确地获取Sandcastle和Sandcastle Help File Builder设置，请按照下列步骤操作： p>

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




2. 下载并安装 http://shfb.codeplex.com/ 上的Sandcastle帮助文件生成器（忽略有关MSHelp2的警告，如果您得到任何东西，你不需要它。）




3. 你有安装然后使用沙堡帮助文件生成器创建一个新的文档项目。当它询问您在哪里保存文件时，将其保存在您的解决方案/项目中的文档文件夹中。
   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文件。 （如果您引用编译的DLL，则sandcastle也可以使用，但是由于您将其与Visual Studio集成，所以发现更适合参考项目/解决方案文件，这也可能意味着您的项目无关紧要做这个post-build事件，因为它引用了代码，而不是DLL，但最好是安全的，并把它放在最后一个项目中。
   http://www.chevtek.com/Temp/AddSource.jpg




7. 保存项目，您可以关闭沙堡帮助文件生成器。现在都设置了。只需将文档项目文件放在批处理命令在Post-build事件中指向的相应文件夹中。

我希望我的简短教程可以帮助你！我很难找到任何体面的教程，告诉我如何使用沙堡，更不用说如何将它与视觉工作室进行整合。希望未来的Google搜索将会提出这个问题。

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.

解决方案

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

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.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"

:Exit

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.

A couple notes:

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

• 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.

Installing Sandcastle and "Sandcastle Help File Builder".

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

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.

2. 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.)

3. 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

4. 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

5. 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.

6. 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

7. 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.

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屋！