Sandcastle: generating class diagram documentation

In the continuation of the article about the auto-generation of documentation on XML .NET code comments with Sandcastle, I decided to talk a little about the Drawbridge component. It allows you to embed clickable class diagrams exported from Visual Studio into your documentation. You can click on the class and go directly to its description. A trifle, but nice ...


In a previous article, the author told how to fasten his GUI shell to the Sandcastle documentation generator to conveniently configure what we want to get as a result. I will not dwell on this in detail.
Let us have:

• Microsoft .NET Framework 3.5
• Visual Studio 2008 (SP1)
• An Xml-documented project, say, in C #

Install

I will make a reservation right away that I put all these applications in the default directories, so that later in the heap of xml configs I did not fix the path. So:

1. Download and install Sandcastle 2.4.10520 . This is the main “engine” of the entire ensemble, which analyzes xml comments in the code and analyzes the assembly directly using .NET Reflection. The documentation (chm, HxS, asp .net) is then built from its output.
   
   After installation, Sandcastle is “registered” through the system environment variable:
   DXROOT = “C: \ Program Files \ Sandcastle \”
2. Let's try to build the documentation in the form of a * .chm file , so download the Microsoft HTML Help Workshop 1.32 . He will receive the output from Sandcastle and issue Documentation.chm “on a silver platter”
3. For the convenience of setting the parameters for building documentation (target solution, copyright, feedback email), download the Sandcastle Help File Builder 1.8.0.2 Beta . This is a GUI, as a result of which an xml file with documentation construction parameters (* .shfbproj) is obtained. He subsequently served at the input of the "generator" Sandcastle.
   
   It will also be written in the system environment variables (% SHFB%) , so after installing all the "code clarity guardians", it would be desirable to restart the computer.
4. To embed clickable class diagrams in the documentation, use Drawbridge 2.1.3 . Download and install. The component has not been updated for a long time, the last release was February 26, 2008, and the author used several third-party libraries when creating it, so the code, unfortunately, is closed. But, most importantly, it works. =)
   
   To make Drawbridge friends with Sandcastle + SHFB, we use street magic suggested by the author of SHFB. In the directory to the installed Sandcastle ( C: \ Program Files \ Sandcastle \ ProductionTools ) add (create) the file BuildAssembler.exe.config with the contents:
   
   

   

 
    
     
                 publicKeyToken="31bf3856ad364e35" culture="neutral"/> 
        
     
   
 


* This source code was highlighted with Source Code Highlighter.

   
   
   Drawbridge naively believes that he will have to work, apparently, in some previous version of the Sandcastle + SHFB bundle and therefore after installation he simply adds the declaration of his assembly to one of the SHFB directories:
   C: \ Program Files \ EWSoftware \ Sandcastle Help File Builder \ BuildComponents \ drawbridgecomponent.config
   
   But SHFB in GUI will not see it. Therefore, to register Drawbridge, you need the contents of this config, between

   …

   add down file:
   C: \ Program Files \ EWSoftware \ Sandcastle Help File Builder \ SandcastleBuilder.Components.config

That's all.
The most interesting thing remained: to comment on the project and generate documentation.

Hello world!

Our HelloWorld:

HelloWorld \ sand \ HelloWorld.shfbproj	Config for generating documentation created in SHFB
HelloWorld \ src \ HelloWorld.sln	Solution, the designer himself
HelloWorld \ src \ HelloWorld \ *	Project files
HelloWorld \ src \ HelloWorld \ diagram	Here I saved diagram class files from Visual Studio (* .cd)
HelloWorld \ src \ HelloWorld \ drawbridge	Here I saved diagram classes exported to images (* .jpg)

We write a simple Solution:

In the picture above, for the Program class, we indicated that we want to see the class diagram “Person.cd” in its description.

Do not forget to enable XML generation when building the assembly in the project properties, on the Build tab:



Now, if the soul of the poet asks to draw a class diagram in Visual Studio - we draw by built-in tools.
Save * .cd to HelloWorld \ diagram , and at the same time export all the drawings in * .jpg to HelloWorld \ drawbridge . Easy and laid back. =)



We create a project for building documentation: HelloWorld \ sand \ HelloWorld.shfbproj , as described in the previous article , and add the “Drawbridge Class Diagram Generator” in the components and configure it accordingly, directing the folders to the true ones:

Generating Documentation.

Documentation generation proceeds with a plentiful amount of logs. If we build it from the GUI via SHFB, then it looks like this:



If the operations were successful, then the following entries will be reflected in the logs:

...
Info: DrawbridgeComponent: Instantiating component.
Info: DrawbridgeComponent: [CastleApps.Drawbridge.Component, version 2.1.3.0. Copyright © 2008 ..]
Info: DrawbridgeComponent: Extracting conifiguration from sandcastle.config (success): True
...
Merging custom build component configurations
C: \ ... \ Projects \ HelloWorld \ sand \ Help \ Working \ sandcastle.config
Replacing default configuration for 'Code Block Component' with the custom configuration
Added configuration for 'Drawbridge Class Diagram Generator' after 'Microsoft.Ddue.Tools.TransformComponent' (instance 1)
No additional help attributes defined. The 'HTML Help 2 Attributes' component was not added.
Last step completed in 00: 00: 00.0313
...
Info: DrawbridgeComponent: T: TestExample.HelloWorld.Program: class diagrams found = 1
Info: DrawbridgeComponent: T: TestExample.HelloWorld.Program: found diagram 'person'.
...

Build.

If everything works, then the documentation does not have to be built through an interface.

1. You can directly set some * .cmd file:
   msbuild.exe HelloWorld.shfbproj

2. 

  
          Properties="Configuration=Debug;Platform=AnyCPU;OutDir=$(Help)" />


* This source code was highlighted with Source Code Highlighter.

Finally.

The clickable class diagram in the documentation will look like below in the picture. Tycking on an interesting class for us, we immediately go to the corresponding page of the documentation. Nicely. =)



Or even in the form of asp pages:



PS
Winding up such curlers, it becomes pleasant that you can get rid of all this in a couple of clicks without touching the comments of the code. Unless they stop working:

///

So why not give it a try?