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.

Answer 1

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.

Answer 2

I must admit that I find the current version of Sandcastle a bit lacking; for large projects it is quite slow, and it isn't easy to integrate (since it is still early).

For regular use, I actually find it easier just to point reflector at a folder with the dll and xml files - IIRC, it will load the xml file(s) as you navigate around.

Plus I almost always have reflector open anyway...

[edit] checked, and yes - xml comments show in the disassembler panel

Answer 3

Install these:

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

Then use the NDocConsole.exe command line to generate documentation in either MSDN or CHM form:

@c:\progra~1\NDoc\NDocConsole.exe MyCode.dll,MyCode.xml -Documenter=MSDN-CHM

I myself have made an External Tool for this and gave it a shortcut, but as the previous poster said you can hook it up to a postbuild event and there you go.

(PS I have been using the setup above for a few years now and am very happy with it)