Generate html documentation automatically during a build with Sandcastle

Question

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.

Solution 1

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.

Solution 2

I recommend you install Sandcastle Help File Builder from Codeplex.

You can run this from the command line, e.g. from a Post-Build event. The simplest command line is:

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

Sandcastle is very slow, so I only run it for Release Builds. To do this, create a Post-Build event with a command something like the following, which passes the configuration name to a batch file:

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

Then inside the batch file you can test if the first argument is "Release" and if so run SandcastleBuilderConsole.exe.

Solution 3

An easy way to do this as suggested above is using Sandcastle Help File Builder. There have been some changes made to the build process from the command line and now these projects can be built with MSbuild instead of SandcastleBuilderConsole.exe. So all you have to do is:

MSbuild.exe ProjectName.shfb

Comments

[Adam McKee]

I do this already in the post-build script, i just check the configuration name to make sure it's "Documentation" (i have 3 configs, debug, release & documentation).

[Joe]

Even better. Means you can create release builds fast without the doc.

[Marc Gravell]

As you like. The main use I can see of Sandcastle is with ISVs; for internal use, I'm happy just to have the comments in a navigable way that doesn't involve VS... reflector gives me that ;-p

[Adam McKee]

Well it's looking like quite a pain to setup so chances are it's going to get left behind ;)

[Adam McKee]

NDoc doesn't fully support .NET 2.0 and I'll be using the tool with .NET 3.5 / Silverlight (hence why the original question said "sandcastle").