In the .NET 1.1 days, documentation could be generated easily and freely using nDoc. Understandably, the fact that it was free is partly why nDoc has now been discontinued.
Since nDoc doesn”t support .NET 2.0, you”ll need something else to make CHM and other help files for your new Visual Studio projects. That”s where SandCastle, the documentation tool recently provided by Microsoft, comes into play. SandCastle is the new free .NET 2.0 documentation tool of choice (if not the only one), and there”s a new Septmber 2006 CTP version out. SandCastle is heavily command-line driven, with many steps involved, which is not what I like to deal with when I need to make documentation. I”d rather automate it, which is where SandCastleBuilder (one of several tools that can automate SandCastle steps). Here”s a quick walkthrough on how to use SandCastleBuilder and SandCastle to generate rich help files quickly and easily.
Download the Files
- First look in your Add/Remove Programs and remove older versions of SandCastle and any helper UIs. You can keep HTML Help Workshop installed, though.
- Get SandCastle: Go to SandCastle”s Wiki at sandcastledocs.com. There should be a link to download the latest version of SandCastle (you can get the September 2006 CTP here).
- In order to generate HTML help 1.x .CHM files (my recommendation), download HTML Help Workshop here.
- To generate HTML Help 2.0 .HxS files, then
- Get a tool to automate SandCastle. I highly recommend Eric Woodruff”s SandCastleBuilder — it looks very similar to nDoc, supports a lot of features, and unlike many of the other supporting tools, it worked for me the first time around and has been updated to support the latest SandCastle CTP. It”s interface is a little more imposing than some of the other tools, but you can run it with my of the default settings.
Fixing a bug with the September CTP (optional)
SandCastleBuilder can generate your help files as CHM files, HxS files, and/or as navigatable websites that look a little like MSDN”s online documentation. If you only want to make a CHM or HxS file, you can skip this step. Otherwise, if you want to create a navigatable help website you”ll need to fix a small SandCastle bug according to the SandCastleBuilder”s documentation:
With the September 2006 CTP, when generating the help as a website, the resulting output will cause JavaScript errors when loaded in Internet Explorer. This is the result of a bug in one of the script files that tries to access a style sheet with an MS-Help format URL. Open up the PresentationPrototypesScriptsStyleUtilities.js file in the SandCastle installation folder and change the getStyleDictionary() function to the following:
function getStyleDictionary() {
var dictionary = new Array();
// iterate through stylesheets
var sheets = document.styleSheets;
for(var i=0; i<sheets.length;i ) {
var sheet = sheets[i];
// It can”t handle ms-help URLs
if(sheet.href.substr(0, 8) == “ms-help:”)
continue;
// get sheet rules
var rules = sheet.cssRules;
if (rules == null) rules = sheet.rules;
// iterate through rules
for(j=0; j<rules.length; j ) {
var rule = rules[j];
// add rule to dictionary
dictionary[rule.selectorText] = rule.style;
}
}
return(dictionary);
}
Configuring a SandCastleBuilder Project
- Open up SandCastleBuilder. If you”ve used nDoc before you”ll notice a similar interface, and you can import old nDoc projects. For this post, though, we”re going to start from scratch.
- Pick Project->New Project from Visual Studio Project
- Navigate to and select a Visual Studio Solution file. SandCastleBuilder will ask you which configuration to use for loading assembly information. You can choose your Debug or Release configuration.
- You”ll see the assemblies listed under “Assemblies to Document.”
- Go ahead and save the Help Project for now by clicking Project->Save Project in the menu.
- In the Build/HelpFileFormat, the default setting is HtmlHelp 1.x. You can change it to other formats if you want.
- In the Build/Dependencies section, you”ll need to specify any assemblies your project is referencing. That includes third party DLLs and the .NET DLLs. So, open the Documentation Assembly References dialog and add a folder dependency to the version of .NET you”re using (e.g. C:WINDOWSMicrosoft.NETFrameworkv2.0.50727). Make online casino sure your project is built, and add another folder dependency to your project”s bin directory, since third party DLLs will probably be copied there.
- Next, click the Namespaces button in the upper right. Here you can indicate which namespaces should be documented. Normally you wouldn”t want documentation for any namespaces that contain web pages. You may have to doubleclick in order to uncheck a namespace. While you”re in there, give your namespaces a summary description in the large textfield below the namespace list.
- If you want, fill in the fields in the Help File section like Copyright, Header Text, HelpTitle, etc.
Generate the Help Files
- In the Build/HelpFileFormat, the default setting is HtmlHelp 1.x. You can change it to other formats if you want, e.g. HtmlHelp1.xAndWebSite will give you a CHM file and a web site
- The Paths/OutputPath section determines where your help files will be placed. By default it”s in a subdirectory called “Help” inside your project folder. Note that when SandCastleBuilder generates help files, everything in this directory is erased, so if you already have a “Help” subdirectory with stuff in it, change Paths/OutputPath to a different (empty or nonexistent) directory name.
- Go ahead and save your Help Project, then click Documentation->Build Project. It”ll take several minutes for your help file to build, so go get a sandwich.
- If the generation ends abruptly with an error saying “Unresolved assemby reference”, add that assembly to the Build/Dependencies collection, save the Help Project, and try again.
- You should now have help files inside the Paths/OutputPath (normally <your project directory>Help). If you set the Build/HelpFileFormat to create a help website, the files will be inside this directory, too.
Automatically Generating Help Files in Visual Studio Whenever You Compile Your Project
If you want to generate your help files automatically whenever you compile a new release version of your project, follow these instructions (from the SandCastleBuilder help):
Right click on the project name in the Solution Explorer, select Properties, and select the Build Events sub-item. Click in the Post-build Event Command Line option to enter the command line to run. You can click the Edit Post-build button to open a dialog with a larger editor and a list of available macros.
In a solution with multiple projects that are documented by the same help file builder project, the post-build event should be defined on the last project built by Visual Studio. If the projects are documented individually, you can place a post-build event on each one.
Below is an example of a common command line script that can be used (lines wrapped for display purposes). Replace the path to the tool with the path where you installed it on your PC, and specify the correct location of the SandCastleBuilder project file (.shfb). The IF statement prevents building the help file in debug builds where it may not be needed.
IF “$(ConfigurationName)”==”Debug” Goto Exit
“C:Program FilesEWSoftwareSandcastle Help File Builder
SandcastleBuilderConsole.exe” $(SolutionDir)DocTestProject.shfb
:Exit
Conclusion
That”s pretty much it. I”m sure later versions of SandCastle will feature more, but with the right helper tools it”s pretty easy to get started.
