Click here to Skip to main content
Click here to Skip to main content

Simple XSLT stylesheet for Visual Studio .NET XML documentation

, 21 Sep 2005 CPOL
Rate this:
Please Sign up or sign in to vote.
A simple XSLT stylesheet to convert a Visual Studio .NET XML document into basic HTML.

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:

<?xml-stylesheet type="text/xsl" href="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:

  1. 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.
  2. 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.
  3. 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.
  4. 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 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.

References

Although nothing beats Google when it comes to finding information, I've found the following resources very useful when I needed information on XML, XSL or XPath:

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Emma Burrows
Software Developer
United Kingdom United Kingdom
Emma's first steps in programming took place at primary school over thirty years ago, thanks to a TI-99/4A and the LOGO language. Following a Master's degree in English Studies (obtained, strangely enough, with a paper on the birth of the microcomputer), Emma started her career in IT.
 
Over the last ten years, she has worked as a localiser, technical writer, editor, web designer, systems administrator, team leader and support engineer, before finally making the move into software development a few years ago. She is now thrilled on a daily basis that she is getting paid for writing code after doing it for free half her life!

Comments and Discussions

 
QuestionComments from VB module not processed through XLST PinmemberLorenBaker11-May-09 14:15 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.141022.2 | Last Updated 21 Sep 2005
Article Copyright 2005 by Emma Burrows
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid