Sandcastle: generating documentation with class diagrams

In continuation of the article about autogenerating documentation for XML comments in .NET code using Sandcastle, I decided to tell you a little about the Drawbridge component. It allows embedding in the documentation of clickable class diagrams exported from Visual Studio. You can zhmaknut the class and immediately go to its description. Trifle, but nice ...


In the previous article, the author told how to fasten a sandbox GUI wrapper to the Sandcastle documentation generator for conveniently configuring what we want to end up with. I will not dwell on this in detail.
Let us have:

• Microsoft .NET Framework 3.5
• Visual Studio 2008 (SP1)
• Xml-documented project, for example, on C #

Install.

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

1. Download and install Sandcastle 2.4.10520 . This is the main “engine” of the whole ensemble, which analyzes xml comments in the code and analyzes the assembly directly using .NET Reflection. From its output, documentation is then built (chm, HxS, asp .net).
   
   After installing Sandcastle, it 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 Microsoft HTML Help Workshop 1.32 . That he will take the output from Sandcastle, and issue "on a silver platter" Documentation.chm
3. For ease of setting the parameters for constructing documentation (target solution, copyright, feedback email), download Sandcastle Help File Builder 1.8.0.2 Beta . This is a GUI, as a result of which the xml file with the parameters for building documentation (* .shfbproj) is obtained. He subsequently and served at the entrance to the "generator" Sandcastle.
   
   It will also be registered in the system environment variables (% SHFB%) , so after installing all the “clarity detectors”, it is advisable 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 friends with Drawbridge Sandcastle + SHFB, use street magic suggested by the author of SHFB. In the directory to the installed Sandcastle ( C: \ Program Files \ Sandcastle \ ProductionTools ) add (create) a file BuildAssembler.exe.config with the contents:
   
   

   <? xml version ="1.0" encoding ="utf-8" ? >
< configuration >
< runtime >
< assemblyBinding xmlns ="urn:schemas-microsoft-com:asm.v1" >
< dependentAssembly >
< assemblyIdentity name ="BuildAssemblerLibrary"
publicKeyToken ="31bf3856ad364e35" culture ="neutral" />
< bindingRedirect oldVersion ="0.0.0.0-2.4.10520.0" newVersion ="2.4.10520.1" />
</ dependentAssembly >
</ assemblyBinding >
</ runtime >
</ configuration >

* 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 his assembly declaration to one of the SHFB directories:
   C: \ Program Files \ EWSoftware \ Sandcastle Help File Builder \ BuildComponents \ drawbridgecomponent.config
   
   But SHFB in the GUI will not see it. Therefore, in order for Drawbridge to register, you need the contents of this config, between

   < component id ="Drawbridge Class Diagram Generator" … > … </ component >

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

That's all.
It remains the most interesting: comment out the project and generate the documentation.

Hello, world!

Our HelloWorld:

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

We write a simple Solution:

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

Do not forget to include the generation of XML when building a build in the project properties, on the Build tab:



Now, if the poet's soul asks to draw a class diagram in Visual Studio, we draw with built-in tools.
Save * .cd in HelloWorld \ diagram , and at the same time export all the pictures in * .jpg to HelloWorld \ drawbridge . Easy and easy. =)



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

Generating documentation.

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



If the operations were successful, then such records 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 conformation 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 necessarily build through the interface.

1. Can any * .cmd file directly incite:
   msbuild.exe HelloWorld.shfbproj

2. <!-- DependsOnTargets="BuildCode" -->
< Target Name ="BuildDocumentation" >
<!-- Build source code docs -->
< MSBuild Projects ="$(SandPath)\HelloWorld.shfbproj"
Properties ="Configuration=Debug;Platform=AnyCPU;OutDir=$(Help)" />
</ Target >

* This source code was highlighted with Source Code Highlighter .

Finally.

A clickable class diagram in the documentation will look like below. Pointing to an interesting class for us, we immediately go to the appropriate documentation page. Nicely. =)



Or even in the form of asp pages:



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

/// <img src= "ClassDiagram.cd" />

So why not try?