Introduction
I admit it; I'm a documentation freak. A decade of technical support and system administration has taught me the value of obsessive documentation. That's probably why I like the XML documentation feature in Visual Studio .NET so much. It's a great tool to make sure your custom classes are intelligible to other developers (and indeed to yourself), and the XML file produced when you compile a project with /doc has the potential to serve as the basis of a simple reference guide.
However, while working on a project recently, I was pondering the question of how to turn this XML file into an HTML format of my choice, and decided that an XSL stylesheet would be a good start. So I did a search in Google for a plain XSL stylesheet that I could easily amend. There are plenty of utilities and third-party programs out there to turn XML documentation files into anything from Word documents to compiled HTML help files, but no simple XSL stylesheets leapt out at me. So I decided to write my own.
Using the Code
The attached ZIP file contains a file called Documentation.xsl. The very simplest way to see what it does to a Visual Studio documentation file is to open the XML file and add the following line after the <?xml version="1.0"?> declaration at the top of the file:
="text/xsl"="Documentation.xsl"
Place Documentation.xsl in the same folder as your XML file. If XML files are associated with a reader that handles XSL (Internet Explorer, for instance), you should see the effect of the stylesheet when you open the XML file. Depending on how the basic HTML heading tags are configured on your system, the result will probably look horrible, as the stylesheet uses the plainest HTML tags available. But that's the point: the next step is up to you.
Changing the Template
Amending the XSL file to suit your own needs is simple. I won't go into the details of how XSL files work, as there are plenty of resources to explain this (see the References section at the end of this article). I'm also assuming that you're familiar with basic HTML. However, you may be able to follow these instructions even if you haven't used XSL stylesheets before.
Documentation.xsl is divided into four sections, identified by uppercase comments in the file:
- Document Template. This section is the template for the entire HTML document. You'll notice that this is where I've put the
<HTML> and <BODY> tags. You could add a <HEAD> section to this template and add a link to a CSS stylesheet, for instance. - Assembly Template. This template handles the information in the XML document's
<assembly> tag, which only contains the name of the assembly (output as a level 1 heading). The most important thing this template does is call the Members Template. - Members Template. This is the one that does the bulk of the work. It loops through all the types in the XML document, and displays their respective fields, properties and methods.
- Other Templates. The other templates in the stylesheet format all the individual tags mentioned in MSDN's XML documentation reference as basic HTML elements, so this is where you would make any change to format a tag in a particular way. For instance, if you wanted all the summaries in the document formatted in green, you would amend the
<xsl:template match="summary"> section.
I've added some comments to the XSL file which should explain what it's doing when loops and conditional statements are involved, and I also put all the HTML tags in uppercase. I'm hoping this will make the file simpler to understand and amend.
The Next Step
Once you've changed the XSL file to suit your needs, you'll be able to use it to output an actual HTML document. You can do this using the .NET Framework's extensive XML classes, or simply using one of the many utilities available on the web. But all that is a different story; a search in the "SOAP and XML Topics" section of this website is probably a good place to start.
Feedback
Although I tried to be as thorough as possible while designing this stylesheet, I must admit that I didn't test it with all the possible tags, so some could probably be formatted better. If you think there are any tags which could be better handled, let me know and I'll amend the stylesheet.
History
- First version produced in February 2005
- Second version produced in September 2005 - moved the copyright notice after the first XML line.
- October 2018 - removed References section as every single link was broken
