Genera automaticamente la documentazione html durante una build con Sandcastle

Question

Quali passi devo prendere per ottenere la compilazione automatica della documentazione HTML tramite il passo di compilazione in Visual Studio? Ho tutti i commenti sul posto e il file commenti.xml generato e Sandcastle installato. Devo solo sapere cosa aggiungere al passaggio post-build per generare i documenti.

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

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

Answer 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

Answer 4

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 5

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)