Sandcastle
From EQUIS Lab Wiki
Contents |
Sandcastle - Documentation Compiler for Managed Class Libraries
XML Markup Codes
Sandcastle can be used build program documentation from XML comments embedded in your source code.
Here is an example of the XML comments for the Get method used in the Timeline class.
/// <summary>
/// Returns a value for the given time. Producing this value may require interpolation
/// or extrapolation.
/// </summary>
/// <param name="t">the time</param>
/// <returns>A time line value</returns>
/// <remarks>
/// It is good practice to call this the Ready method before using the
/// Get method to ensure that Get will not return an error.
/// </remarks>
/// <example>
/// <code>
/// protected override void Draw(GameTime gameTime)
/// {
/// if (playerPosition[other].Ready())
/// {
/// TankStatus otherShip = playerPosition[other].Get(-REMOTE_LAG);
/// }
/// }
/// </code>
/// </example>
public ValueType Get(int t)
{
.
.
.
.
return result;
}
A description of the markup language can be found at: http://www.codeproject.com/KB/XML/csharpcodedocumentation.aspx
Using Sandcastle
Downloading and Configuration
Download from here: http://sandcastle.codeplex.com/releases/view/47665
The first time I tried to use the program, all the folders were readonly which caused problems because the documentation gets put in the same folders as the program and there is no error message that indicates why you got no results.
The only place the Gui interface gets installed seems to be in Examples\Generic
In this folder there is a file vs2005.config Edit this file with a text editor and remove the lines highlighted in red below. This removes the syntax for Visual Basic, C++ and J Sharp
<component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<if condition="not(starts-with($key,'Overload:') or starts-with($key,'R:'))" />
<then>
<component type="Microsoft.Ddue.Tools.SyntaxComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<syntax input="/document/reference" output="/document/syntax" />
<generators>
<generator type="Microsoft.Ddue.Tools.VisualBasicDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
<generator type="Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
<generator type="Microsoft.Ddue.Tools.CPlusPlusDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
<generator type="Microsoft.Ddue.Tools.ScriptSharpDeclarationSyntaxGenerator" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />
</generators>
</component>
</then>
</component>
in the transform section, change this:
<component type="Microsoft.Ddue.Tools.TransformComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<transform file="%DXROOT%\Presentation\vs2005\Transforms\main_sandcastle.xsl">
<argument key="metadata" value="true" />
<argument key="languages">
<language label="VisualBasic" name="VisualBasic" style="vb" />
<language label="CSharp" name="CSharp" style="cs" />
<language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
<language label="JavaScript" name="JavaScript" style="cs" />
</argument>
</transform>
</component>
This causes it to only show the syntax for C# and not the other languages
Running the Program
Run SandcastleGui.exe
Enter a name in the top right. This will be the name of the folder where it puts the documentation.
Check both chm and Web to get html output
In the Assemblies section, click on Add and browse for the dll files to be documented
In the Comments section, click on Add and browse for the xml documentation files. The Visual Studio puts the XML documentation in the debug folder. Look for it there.
In the Dependent Assemblies section, click on Add and browse for the dependent dll files.
Click on Build
You will be prompted to save the project file
When it is done you get this message
Finding the Output
Your documentation will be a subfolder of Examples. If the name you used was JanusToolkit, the documentation can be found at Examples\JanusToolkit\vs2005\output\html
There are also other forms of documentation created such as a chm help file
If you copy the help files to the web, you must copy all the folders under output. Also, you need to change the upper case P in the file name styles\Presentation.css to lower case styles\presentation.css or the web pages will no longer look good.
