Click here to Skip to main content
15,867,308 members
Articles / Programming Languages / XSLT

Simple XSLT stylesheet for Visual Studio .NET XML Documentation

Rate me:
Please Sign up or sign in to vote.
4.59/5 (44 votes)
21 Sep 2005CPOL4 min read 299.6K   7.8K   82   47
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
<?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 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

License

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


Written By
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

 
QuestionIssue with Classes wich starts with the same part of the name Pin
Giovefi3-May-22 18:20
Giovefi3-May-22 18:20 
GeneralMy vote of 5 Pin
Member 1458526112-Sep-19 16:31
Member 1458526112-Sep-19 16:31 
Questionhumble permission request Pin
Member 1458526112-Sep-19 19:39
Member 1458526112-Sep-19 19:39 
BugNon-covered case Pin
Jaime Olivares14-Sep-15 17:08
Jaime Olivares14-Sep-15 17:08 
QuestionGreat work, thanks for publishing this! Pin
bcbowen22-Jan-15 8:51
bcbowen22-Jan-15 8:51 
AnswerRe: Great work, thanks for publishing this! Pin
jpbj04033-Apr-15 5:48
jpbj04033-Apr-15 5:48 
BugDoesn't work! Pin
denko8311-Jan-15 14:03
denko8311-Jan-15 14:03 
Questionno output Pin
alessandro.cortese10-Feb-14 6:31
alessandro.cortese10-Feb-14 6:31 
QuestionUnable to view output in Chrome Pin
abhishekpratik4-Sep-13 22:01
abhishekpratik4-Sep-13 22:01 
AnswerRe: Unable to view output in Chrome Pin
Emma Burrows5-Sep-13 1:44
Emma Burrows5-Sep-13 1:44 
Generalimprovement / bugfix Pin
LotharLanger19-Oct-10 20:51
LotharLanger19-Oct-10 20:51 
Generaleasy way to use the xslt within Visual Studio Pin
Patrick Lambourne30-Sep-10 5:19
Patrick Lambourne30-Sep-10 5:19 
GeneralMy vote of 5 Pin
thatraja26-Sep-10 20:00
professionalthatraja26-Sep-10 20:00 
GeneralThanks Emma Pin
Kevin R. Scott23-Sep-10 8:49
Kevin R. Scott23-Sep-10 8:49 
GeneralCSS to make it a little nicer Pin
Reinderien15-Apr-10 8:31
Reinderien15-Apr-10 8:31 
Generalis there anyway to add the xslt reference to the generated xml Pin
Frédéric Steczycki17-Mar-10 8:00
Frédéric Steczycki17-Mar-10 8:00 
QuestionComments from VB module not processed through XLST Pin
LorenBaker11-May-09 14:15
LorenBaker11-May-09 14:15 
QuestionProblem with methods selection [modified] Pin
Kevin_M30-Mar-09 11:44
Kevin_M30-Mar-09 11:44 
GeneralJust what I was looking for Pin
norsemonster29-Oct-08 11:38
norsemonster29-Oct-08 11:38 
Generalvery usefull Pin
gdeenen26-Aug-08 23:58
gdeenen26-Aug-08 23:58 
GeneralGood Article Pin
sujith ms3-Jun-08 15:00
sujith ms3-Jun-08 15:00 
QuestionHi Pin
MohsenElahi18-Mar-08 13:19
MohsenElahi18-Mar-08 13:19 
GeneralXML comments : shortcoming Pin
aliascodeproject22-Aug-07 1:41
aliascodeproject22-Aug-07 1:41 
GeneralA great find! Pin
mpennell28-Jun-07 13:53
mpennell28-Jun-07 13:53 
GeneralThanks Pin
TracyW16-Feb-07 8:53
TracyW16-Feb-07 8:53 

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

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