Geeks With Blogs

News
View Szymon Kobalczyk's profile on LinkedIn

Szymon Kobalczyk's Blog A Developer's Notebook

As you probably already know, NDoc developer Kevin Downs resigned from continuing this project, but at the same time Microsoft announced it's own tool called Sandcastle that can generate documentation from code comments in any .NET language. Like many of you I was waiting long for NDoc to support .NET 2.0, and had to bear with no documentation for a while. Therefore I was eager to try out what this Sandcastle can do for me. The good news is that Sandcastle was released this weekend, so here are my first impressions.

After you download and install the MSI you might want to try building the provided example, either by manually following directions or by using the PowerShell script created by Scott Hanselman. It worked fine for me and soon I got the CHM for the example class. A lot of steps but at least it worked. So the next obvious thing was to do the same process for one of my own projects. Here things didn't went so smoothly.

The problems started already on the first command:

> MRefBuilder MyProject.dll /out:reflection.org
MRefBuilderStatic (v2.0.2397.42473)
Copyright Microsoft Corp. 2005
Error: Unresolved assembly reference: System.Configuration (System.Configuration, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a) required by MyProject

Apparently this tool requires you to manually provide paths to some of the referenced assemblies (it is unknown to me why it asked for this one and didn't bother with others). In this case the proper command is:

> MRefBuilder MyProject.dll /out:reflection.org /dep:"c:\Windows\Microsoft.NET\Framework\v2.0.50727\System.Configuration.dll"
MRefBuilderStatic (v2.0.2397.42473)
Copyright Microsoft Corp. 2005
Info: Loaded 2 assemblies for reflection
Info: Wrote information on 48 namespaces, 746 types, and 4611 members

In result I got the first XML file with the reflection information. Using that file I did couple of XslTransforms and got two additional XML files: reflection.xml and manifest.xml. After that you need to run CopyOutput.bat to create output directory structure.

Next step is running BuildAssembler, but first you need to provide configuration for it. In provided example it is copied from Presentation\Configuration\Sandcastle.config. The problem is that this file contains relative paths so if you copy it to your working folder in most cases it won't work, as it didn't for me on the first try:

> BuildAssembler /config:sandcastle.config manifest.xml
BuildAssembler (v2.0.2389.25323)
Copyright 2005 Microsoft Corporation
Error: BuildComponent: A file access error occured while attempting to load the component assembly '
..\..\ProductionTools\BuildComponents\BuildComponents.dll'. The error message is: Could not load fil
e or assembly 'file:///D:\Work\MyProject\ProductionTools\BuildComponents\BuildComp
onents.dll' or one of its dependencies. File not found.

You need to manually change the Sandcastle.config file to point to the correct directories. For now I just replaced all the '..\..' with “C:\Program Files\Sandcastle”. When you edit this file you might also look at two things. First if you use any third-party assemblies in your project I guess you might want to create reflection information for them as well (even if you are not include them in your documentation). You can reference this data in the second section (commented with: “Copy in reflection data”). Also note that if you change the name of the reference.xml to anything else you should also change this name in the same section. On the same note if XML documentation file for your assembly has different name then comments.xml (probably it has) you should change this name in the fifth section (commented with: “Copy in comments”). Here you can also provide XML documentation for additional assemblies.

After applying this changes I run the BuildAssembler again. It run for few seconds spiting bunch of Infos and Warns to the console and... finally crashed. So this is all I've got instead of my shinny new documentation:

Unhandled Exception: System.NullReferenceException: Object reference not set to an instance of an ob
ject.
   at Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator.WriteNormalMethodSyntax(XPathNavigator r
eflection, SyntaxWriter writer)
   at Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator.WriteMethodSyntax(XPathNavigator reflect
ion, SyntaxWriter writer)
   at Microsoft.Ddue.Tools.SyntaxGeneratorTemplate.WriteMemberSyntax(XPathNavigator reflection, Synt
axWriter writer)
   at Microsoft.Ddue.Tools.SyntaxGeneratorTemplate.WriteSyntax(XPathNavigator reflection, SyntaxWrit
er writer)
   at Microsoft.Ddue.Tools.SyntaxComponent.Apply(XmlDocument document, String key)
   at Microsoft.Ddue.Tools.IfThenComponent.Apply(XmlDocument document, String key)
   at Microsoft.Ddue.Tools.BuildAssembler.BuildTopic(XmlReader reader)
   at Microsoft.Ddue.Tools.BuildAssembler.Main(String[] args)

For now I give up, but I would by glad if anyone can help me figure out what went wrong here. However, in my opinion this tool is not ready to be released yet and we need at least to wait for some bits of instruction before we can use it (it's sorts of funny that tool intended to produce documentation doesn't contain any documentation on its own ;-)

UPDATE: There is a short FAQ published on the Sandcastle blog that might answer some of your questions. You might also take a look at some helper toolsGUIs and scripts created by the community.

Posted on Sunday, July 30, 2006 9:37 PM Development | Back to top


Comments on this post: Did you try Sandcastle?

# re: Did you try Sandcastle?
Requesting Gravatar...
You can set the dependancy path as per the FAQ. However I haven't tried this - I solved this by modifying the .config file changing the ..\..\ to the absolute path to sandcastle install folder. I did this plus two other modifications to the config for my BAT script:

http://ixnay2infinity.blogspot.com/2006/07/improved-sandcastle-bat-script.html
Left by Ashley van Gerven on Jul 31, 2006 8:56 AM

# re: Did you try Sandcastle?
Requesting Gravatar...
I've created a MSBuild script that helps automate the process a bit. Maybe it can help you out? I'd appreciate any comments!

http://blog.ljusberg.com/2006/07/msbuild-script-for-sandcastle.html

Regards,

Anders Ljusberg
Left by Anders Ljusberg on Jul 31, 2006 1:53 PM

# re: Did you try Sandcastle?
Requesting Gravatar...
Ugh...this only rubs salt into the wound.

Microsoft should just "adopt" NDoc somehow (donate a software engineer or two? pick up the codebase?).

Sandcastle, from the looks of it, is still rather immature.
Left by Charles Chen on Jul 31, 2006 5:38 PM

# re: Did you try Sandcastle?
Requesting Gravatar...
Can you modify sandcastle.config to make sure its pointing correctly to BuildComponents.dll.

You need to modify

..\..\ProductionTools\BuildComponents\BuildComponents.dll'

Left by pritam on Jul 31, 2006 5:41 PM

# re: Did you try Sandcastle?
Requesting Gravatar...
As I wrote in my post, I *did* change the sandcastle.config to absolute paths for BuildComponents.dll. After that the BuildAssembler run for a while but finally crashed with the NullReferenceException reproduced above. I still haven't found any couse or solution for this.
Left by Szymon on Jul 31, 2006 6:05 PM

# re: Did you try Sandcastle?
Requesting Gravatar...
Szymon,
Send your dll's to me at prit_bhat@hotmail.com and i will look into this issue.
Left by pritam on Jul 31, 2006 11:25 PM

# re: Did you try Sandcastle?
Requesting Gravatar...
You guys should take a look at the free adin Process Academy made to generate documentation using sandcastle. The plugin is really easy to use and free to download.

Go to http://www.processacademy.ca to give it a try.
Left by Louis on Aug 07, 2006 9:03 PM

Your comment:
 (will show your gravatar)


Copyright © Szymon Kobalczyk | Powered by: GeeksWithBlogs.net