Output
Output Format
There are three formats you can choose:
- Compiled Help File (.chm)
- This is the standard for software help files, containing a table of contents , index and search modules. The extracts used in the article have been copied from a compiled help file or .chm file.
- Linked HTML Files (.html)
- This format creates multiple interconnected .html files , this is really cool if you want to publish your database documentation on your intranet.
- Compiled Help File Format HTML 2.0 (.hxs)
- This is the new help file format as used in Books Online of SQL 2005. To use the .hxs format you need to have the Visual Studio Help Integration Kit installed.
Formatting
Here you can choose the style sheet for your documentation , it comes with 2 style:
VS2005 :
And another basic style sheet:
Custom Text
The custom text determines what will be displayed at the top and the bottom of each documentation page. This section accepts tags such as {date} , {time} , {author} etc.
If you want to use the author tag, make sure that you have specified the author in the Copyright step.
Naming
Specify your documentation title and filename. This step also allows you use some tags such as the {datasourcename} and {databasename}. If you are documenting multiple servers at the same time, this can become a little messy, so I would suggest coming up with a different naming convention and maybe adding the {date} tag.
Copyright
Add your copyright and author information for a nice touch.
HxS Attributes
If you have selected Hxs as your format a new step is added to allow you the specify a namespace template.
The Custom Descriptions Editor
As I mentioned before, extended properties allow you to add text and descriptions to database objects. Conventionally extended properties had to be added using the syntax similar to this:
USE AdventureWorks;
GO
EXEC sys.sp_addextendedproperty
@name = N’MS_Description’,
@value = N’Minimum inventory quantity.’,
@level0type = N’SCHEMA’, @level0name = Production,
@level1type = N’TABLE’, @level1name = Product,
@level2type = N’COLUMN’, @level2name = SafetyStockLevel;
GO
This version of ApexSQL Doc includes a Custom Descriptions Editor. You can access it by clicking on the tools menu.
The Custom Descriptions Editor will display all of the extended properties in your database for the selected extended properties name. If you want to add your own extended properties name you can do that here by typing it in the Extended Property Name dropdown.
You can then go ahead and add or alter extended properties by typing it into the description field of the grid, next to the object you’d like to add it to. It’s fairly easy to use, but once you have applied your extended properties be sure to refresh your Extended Properties Name dropdown, because this unfortunately doesn’t update automatically afterwards.
Extended properties are added at object level, so be sure to drill down to get to objects like stored procedure parameters etc.
You can also add an extended property to your database itself by clicking on the “Add Extended Property To Database” link at the top of the Custom Descriptions Editor window.
Compiling the documentation
Once you are satisfied with the options you have selected click on the finish button to start compiling the documentation. This can take a couple of minutes, depending of course on the size of the database and the options you have selected. A progress bar will indicate your progress.
Once complete you will be prompted to view the file. Click yes to see the result. Here is an example page pulled out from my created documentation to give you an indication of what to expect;
This is a trigger in the AdventureWorks database.
This section is specified in the Trigger options step of the wizard which is only added to the wizard, if you have selected Triggers in the Object type step.
This section is included base on the settings in the Dependency Options step.
Had there been any extended properties created for this trigger through the custom description editor it would have appeared in this section. Although no properties have been defined the section is still included as per the setting in the Database Options step.
The DDL script is included as specified in the Database Options step.
Command Line Integration
An interesting idea might be to incorporate documentation into your nightly build. ApexSQL Doc can facilitate this for you with its command line integration.
To create basic documentation can be as easy as specifying the server and database name, using the following syntax:
ApexSQLDoc /s:(local) /d:AdventureWorks
However I highly recommend specifying the output directory , or you might end up wondering where your documentation went i.e.
ApexSQLDoc /s:(local) /d:AdventureWorks /od:C:Temp
Everything which can be set in the GUI can be set in the command line as well , using the appropriate switch. If nothing is set the application defaults will be used.
To make things really easy however, you can use the ApexSQL Doc GUI to set up all of your preferences and save it as a project. This project file (.axdp) can then be passed as a parameter in the command line to generate the documentation based on the project settings.
ApexSQLDoc /pr:C:MyProject.axdp /od:C:Temp
One thing to remember is to specify the complete path to the executable and the project file you might wish to use, and even when using the predefined project file, make sure to still define the output directory.
Conclusion
I can certainly say that after using ApexSQL Doc I will never go back to doing database documentation the conventional way. I specifically find the Custom Description Editor to be a saving grace, since I can now have all of my descriptions in my database and have it included in my documentation every time without any additional effort.
If you have never used a documentation tool before I can definitely recommend it, you will be amazed at the quality and comprehensiveness of the generated documentation.
]]>