Integrating sandcastle into build process to generate MSDN style documentation
A well documented code is always a good thing especially when it comes to maintaining it. I’d like to remind you guys a quote from Rick Osborne
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. ”
In this article I will walk through how to integrate Sandcastle tool to generate MSDN style documentation for your code. Before we look at how to get sandcastle tool integrated into your build process, I’d like to remind couple of things.
- If you are not adding XML documentation to your code, start getting into that habit
, all public methods/properties and classes should have XML documentation. For more information on recommended tags please read https://msdn.microsoft.com/en-us/library/5ast78ax(v=VS.100).aspx - You should turn on XML documentation for all your source projects, you can do this by going into project properties and selecting the build option as shown in the picture below
I like to force this in my build script during compile incase people forgot to turn this on, you can set “DocumentationFile” MSBuild property to specify XML documentation file.
Tool
Sandcastle is the recommended tool for generating code documentation, you can download most current version of Sandcastle from codeplex https://sandcastle.codeplex.com/releases/view/47665
I’m used to installing all build tools in a directory called “BuildTools” on my build server, so for the sake of this article we’ll just assume that’s what you guys are doing as well and create a directory “Sandcastle” and install Sandcastle on to this directory.
There are five main components to this solution
- MrefBuilder – Used to generate the reflection xml file for build assembler
- BuildAssembler – Used for syntax generation
- XslTransform – Used to transform reflection xml file to generate the final reflection and manifest xml files used by Build Assembler tool, its also used to generate toc xml file used by “ChmBuilder” tool
- ChmBuilder – Used to generate the “hhp” file (This is the help project file that “hhc.exe” tool is going to need to create your chm file
- Hhc (HTML Help Compiler tool, this is not a part of sandcastle setup, it should already be in the system, you can quickly verify this by opening command prompt and entering hhc.exe)
Sandcastle configuration file modifications (Sandcastle.config)
I recommend creating a directory called “docs” under your project root directory which can be used to store files that are generated by your help system. You can find the sandcastle configuration file at “{sandcastle root}\Presentation\vs2005\configuration” directory, I recommend copying this over to the “docs” directory. Later in the build script you will see that this directory is used as working directory when running the help tools, also script creates “chm” to store required files for “chmbuilder” tool and “html” folder to store html topic files generated by the “BuildAssembler” tool
Open the sandcastle.config file that was copied to the “docs” directory in VS2010 (make sure you are not modifying the original configuration file from sandcastle install directory)
In the sandcastle configuration file you will find references to “%DXROOT%”, this environment variable by default should refer to the directory where sandcastle tool was installed. If you installed VS SDK after you installed Sandcastle that may not be the case as VS SDK install will overwrite %DXROOT% environment variable. So just to be safe, I recommend search for %DXROOT% and replace with path to directory where you installed Sandcastle. So for example in my scenario since I installed Sandcastle tool on “c:\buildtools\sandcastle” directory I would replace “%DXROOT%” with that value. Again this step is not necessary if %DXROOT% environment variable value is referring to the directory where you installed Sandcastle.
Next we need to specify where to find xml documentation files for all of the input assemblies. Search for “.\comments.xml” and replace it with the full path of the xml documentation files. If you have multiple assemblies and xml documentation files, which in real world scenarios you will I recommend copying all the assemblies and xml documentation files into one directory and then you can add “\*.xml” to the directory path for comment files
Next we need to specify where to output the html topic files. Search for “.\output\html” and replace it with “.\html” reason for this is we are using “docs” as current working directory and build script creates “html” directory under “docs”.
This is an optional step, you can specify sandcastle to use the modified version of feedback_content.xml file so it can use settings that are specific for your scenario, replace the path for feedback_content.xml file to point to updated version which contains your specific settings. Similarly you can also use an updated version of shared_content.xml, I’m not going to go through all scenarios, have a look at those xml files and determine changes you need to make to fit to your needs and update the sandcastle.config file so that when documentation is being generated during build process it can use settings specific for your project instead of default ones.
In the msbuild script first we run the “MrefBuilder” tool to generate the reflection xml file, if the input assemblies has references to other third party assemblies use the “/dep” switch to specify them
<Exec Command="$(SandCastleMrefBuilderExe) $(BinDir)\*.dll /out:mref.xml" WorkingDirectory ="$(DocDir)" />
Run the “XSLTransform” tool on the reflection xml file generated by “MrefBuilder” tool to group overloads
<Exec Command="$(SandCastleXslTransformExe) mref.xml /xsl:"$(SandCastleApplyVSDocModelXsl)" /out:afterapplyvsdocmodelxsl.xml" WorkingDirectory="$(DocDir)" />
Run the “XSLTransform” tool again on the output xml from previous transform to generate friend names for HTML topic files
<Exec Command="$(SandCastleXslTransformExe) afterapplyvsdocmodelxsl.xml /xsl:"$(SandCastleAddFriendlyFileNamesXsl)" /out:reflection.xml" WorkingDirectory="$(DocDir)" />
Run the “XSLTransform” tool again on final reflection xml file to generate manifest file
<Exec Command="$(SandCastleXslTransformExe) reflection.xml /xsl:"$(SandCastleReflectionToManifestXsl)" /out:Manifest.xml" WorkingDirectory="$(DocDir)" />
Create the HTML topic files by running “BuildAssembler” tool
<Exec Command="$(SandCastleBuildAssemblerExe) manifest.xml /config:$(SandCastleConfig)" WorkingDirectory="$(DocDir)" />
Generate a TOC xml file
<Exec Command="$(SandCastleXslTransformExe) reflection.xml /xsl:"$(SandCastleCreateVSTocXsl)" /out:toc.xml" WorkingDirectory="$(DocDir)" />
Generate Help Project File
<Exec Command="$(SandCastleChmBuilderExe) /project:$(DocChmFile) /html:Html /lcid:1033 /toc:toc.xml /out:Chm" WorkingDirectory="$(DocDir)" />
Generate Chm file
<Exec Command="$(HhcExe) $(DocChmDir)\$(DocChmFile).hhp" WorkingDirectory="$(DocDir)" ContinueOnError="true" />
I have uploaded the Sandcastle demo project along with MSBuild script to code gallery (https://code.msdn.microsoft.com/sandcastleutil), you can use the MSBuild script to integrate it into your build process. Just remember to set “BinDir” and “DocDir” properties before calling the “GenerateCodeDocumentation” target.
Cheers,
</Ram>
Technorati Tags: Sandcastle,Chm,MSBuild