Everyone hates documentation. Especially we programmers. Documentation takes up quite a bit of time, and tends to be out dated by the time it's finished. ASP.NET and self-documenting code with XML comments have brought us a long way, but this still leaves database documentation out in the cold.

In this article, we'll discuss how to use CodeSmith (*1) to build a template that will create HTML documentation for you. Once you finish up your template you can re-generate your documentation at any time, and often (often referred to as "Active Generation"; the act of re-generating code/documentation at often, scheduled intervals or even part of your build process).

One of CodeSmith's greatest strengths is it's similarity to the syntax used in ASP.NET. Immediately, you'll notice the script blocks (<% %>), template properties and <script> blocks. These should be very familiar to you, and you'll find work in much the same manner as ASP.NET.

The first thing you need to do when creating a CodeSmith template is to put in your CodeTemplate directive. This directive tells the template parser the rules to use when parsing and building your template.

In this case, my template looks like:

<%@ CodeTemplate Language="C#" TargetLanguage="HTML" 
        Description="Generates a set of HTML-based database documentation." %>

This particular directive tells the template parser that the template is going to be written in C# (CodeSmith supports any CodeDOM CLR language, but is currently hard-code to support only C#, VB.NET and JScript), and gives a basic description of what your template does. This description is shown as a tool-tip in the Template Explorer window of CodeSmith.

We then need to define any properties that the template will need. Properties are any specific setting that you want users to input when running a template, such as database connection specific settings, specific strings that need to be referenced throughout your template, etc... Properties translate into specific property areas in the Properties window, as well as variables within your script.

For example, here I want to create a property that accepts a string that I'll use as a title within my HTML documentation:

<%@ Property Name="DocumentationTitle" Type="System.String" Default="Database Documentation" Category="Output" 
        Description="Defines what the title of the HTML page that will be generated will be." %>

This directive tells the template parser (and template designer) that there is to be a property called DocumentationTitle, it is a System.String, the default value is "Database Documentation", put it in a group called "Output" (used in the Properties window) and gives a description of the property that is to be displayed within the Properties window.

*1 = The following article is written using CodeSmith Studio in an upcoming release of  CodeSmith Pro", which can be found in the beta forums at http://www.ericjsmith.net/codesmith/forum/.