Simple XSLT stylesheet for Visual Studio .NET XML documentation

Download source files - 1.60 Kb

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:

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 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:

XSLT tutorial. A good place to start if you want to learn about XSL transformations.
MSXML 4.0 SDK documentation on MSDN. Another useful source of information on XML-related topics.
C# Programmer's Reference - XML Documentation. More information on how Visual Studio's XML documentation works.
CodeProject SOAP and XML topics. Other articles about XML-related topics.
microsoft.public.xml. The best place to ask XML/XSL/XPath related questions!

License

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

About the Author

Emma Burrows

Web Developer

United Kingdom

Member

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 for companies ranging from Microsoft to the more modest British software company Equisys. After all this, Emma recently found her dream job as an XSLT developer for a pharmaceutical publishing company, and is thrilled that she's finally getting paid for coding after doing it for free half her life.

Article Top

Poor

Excellent

Add a reason or comment to your vote: x
Votes of 3 or less require a comment

Comments and Discussions

You must Sign In to use this message board. (secure sign-in)

Search this forum
	Profile popups Noise Layout Per page

improvement / bugfix

LotharLanger

20:51 19 Oct '10

Hi Emma,

here is something i wanted to let you know.

In some cases your xsl doesn't do the right thing because your xpath expressions for methods, fields find more than they should.
This happens when names of types start with the same characters, e.g. types "NU" and "NUnit".

The problem can be solved if you include the dot in your second variable:

But instead you would have remove the inclusion in some other cases below.

Hope that this helps.

Otherwise you article is of great help to get started with documentation.

Thanx,
Lothar

easy way to use the xslt within Visual Studio

Patrick Lambourne

5:19 30 Sep '10

If you open the .xml file which contains the xml comments in VS you can use the XML/Show XSLT Output menu item to browse to this .xslt and convert the xml to html. (You will need to delete the blank line at the top of the xslt first)
Sign In·View Thread·Permalink

My vote of 5

thatraja

20:00 26 Sep '10

Good one mam...thanks
Sign In·View Thread·Permalink

Thanks Emma

Kevin R. Scott

8:49 23 Sep '10

This article was just what I needed to get started in the right direction quickly. Thanks a bunch!
Sign In·View Thread·Permalink

CSS to make it a little nicer

Reinderien

8:31 15 Apr '10

To add some CSS to make the styled XML look a little more legible, you can do something like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- ================================================================================ -->
<!-- Amend, distribute, spindle and mutilate as desired, but don't remove this header -->
<!-- A simple XML Documentation to basic HTML transformation stylesheet -->
<!-- (c)2005 by Emma Burrows -->
<!-- ================================================================================ -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
<!-- DOCUMENT TEMPLATE -->
<!-- Format the whole document as a valid HTML document -->
<xsl:template match="/">
<html>
<head>
<style type="text/css">
body {
background-color: #ffffcc;
}
h1, h2, h3, h5, p {
font-family: Georgia,serif;
}
h2 {
color: #993300;
}
h3 {
margin-left: 25px;
}
h4 {
margin-left: 50px;
font-family: lucida console,monospace;
font-weight: normal;
color: #3366ff;
}
h5 {
font-style: italic;
font-weight: normal;
text-decoration: underline;
}
h5, p {
margin-left: 75px;
}
</style>
</head>
  <body>
...

is there anyway to add the xslt reference to the generated xml

Frédéric Steczycki

8:00 17 Mar '10

an automated way to add the style sheet reference (?xml-stylesheet type="text/xsl" href="Documentation.xsl"? line) will be perfect for me. thanks anyway for the work on your XSLT, i just added a reference to our CSS file to have our related style sheet. MS Visual Studio 2008 Fred
Sign In·View Thread·Permalink

Comments from VB module not processed through XLST

LorenBaker

14:15 11 May '09

I also want to thank you for your good work. While I’m new to XLST I was able to follow your code, and I ran tests on XML documents generated from comments included in a couple of simple VB projects. The first XML was from a VB project that included only one class. Your XLST produced output as I would expect.

However, the second XML was from a VB project that had no class, but instead had one module with functions that included comments. While the XML file contained data from the module’s function comments, your XLST did not output this information. I believe the problem arises from the XML document not having any member that contains a ‘T:’ associated with the VB module. Therefore nothing associated with the module gets processed in your XLST. Any suggestions as to how to address this problem?

Thanks for your help.

Problem with methods selection [modified]

Kevin_M

11:44 30 Mar '09

First of all, great work on this XSLT. It really made it easy for me to set up a decent looking and well printing documentation set for my company. Its pretty simple to structure the output HTML and with the addition of a little CSS everything came together nicely. I have run into trouble with the methods section though and I'm hoping you can offer some advice...

The problem is with two similarly named classes in my application. One of them is clsCampaign and the other is clsCampaignManager. The methods selector is pulling all of the methods for clsCampaignManager when displaying clsCampaign's methods. I think this may be because you are using some sort of "contains" function to compare against the method names. I'm not that familiar with XSLT so that may be an incorrect assumption. Do you have any ideas about how I might solve this problem?

Thank you

EDIT:

I have a working (but not thoroughly tested) solution. At least it seems to be working so far Smile | :)

  <!-- If this type has methods, display them -->
  <xsl:if test="//member[contains(@name,concat('M:',$FullMemberName))]">
  <H3>Methods</H3>
    <xsl:for-each select="//member[contains(@name,concat('M:',$FullMemberName<code>,'.'</code>))]">        
        <!-- If this is a constructor, display the type name 
            (instead of "#ctor"), or display the method name -->
		<div class="methodBlock">
        <div class="methodSignature">

Basically what this does, is force the selector to match all the way to the end of the method name because it has to match to the dot ('.') which should always appear after the Type in the namespace string but before the method signature. Please let me know if you think this is a good solution.

Thanks again

modified on Monday, March 30, 2009 7:12 PM

Just what I was looking for

norsemonster

11:38 29 Oct '08

Thank you Emma! You're my hero
Sign In·View Thread·Permalink

very usefull

gdeenen

23:58 26 Aug '08

Thought it would be very simple to find such a file on the internet. This is the only one I found after some searcing that works for me. I have not digged into the syntax of xsl files and just needed one that works.
Sign In·View Thread·Permalink

Good Article

sujith ms

15:00 3 Jun '08

Good XSLT for my XML file generated.. it has been very helpful.. thnaks
Sign In·View Thread·Permalink

MohsenElahi

13:19 18 Mar '08

assemblies and XML documentation files produced by Visual C#.NET
Sign In·View Thread·Permalink

XML comments : shortcoming

aliascodeproject

1:41 22 Aug '07

XML comments are great but they have drawbacks.

I generally find it good for documenting a specific function, but sometimes, I wished there was an efficient way of linking to a more general topic, describing the overall workings of the code. It should be possible to add a link (could be some kind of unique identifier generated by VS inserted into XML comment) to a section of a document (XML,Word or any other appropriate type of document) and to be able to edit this section quickly (VS should be able to follow the link). It would be a great help to keep the more general documentation up to date!

XLM comments also makes the code a bit overloaded... but the benefits are to great to not use them.

A great find!

mpennell

13:53 28 Jun '07

I spent an hour searching for this very thing today ... it was great to find your solution. Thanks for taking the time to contribute back to the community. -Mark h--p/devaustinDAHTworpressDAHTcom
Sign In·View Thread·Permalink

Thanks

TracyW

8:53 16 Feb '07

I am trying to get the group I work with to see the value of XML commenting. I needed a basic XSLT file that I could manipulate (I am too lazy to create it from scratch). Tracy Wallace
Sign In·View Thread·Permalink

Re: Thanks

Emma Burrows

10:22 16 Feb '07

Yes, when I was in a similar situation, I had to write my own - I'm glad I've spared someone the same trouble!
Sign In·View Thread·Permalink

Useful but something's missing

TheOF

1:37 14 Feb '07

Thanks for the article but I mis one thing:

I need to document methods of our web services that return structured XML in various formats.

I include output examples in hte sections but your xsl doesn't copy the XML tags.

I'm not familiar with xsl syntax, any solution?

Thanks.

Example:
C#:
----
///

/// Customer gets more credits to his/her acct
///

///
///
///
///

 

  ///         status"" 

  ///       if fails then extra output: 

  ///         ErrorMessage "; 

  ///      "; 

  ///

/// Example:
///

 

  /// -  

  /// -  

  ///  false 

  ///Invalid object name 'sr.Users'. 

  /// 

  /// 

  ///

///
[WebMethod]
public XmlDocument BuyCredits(string CustomerID, ...)

HTML output:
---------------
...
Return Value:

status""
if fails then extra output:
ErrorMessage ";
";

Example:
-
- falseInvalid object name 'sr.Users'.

...

Thanks in advance Smile | :)

Re: Useful but something's missing

Emma Burrows

10:16 14 Feb '07

In fact, your tags are technically still there - the stylesheet isn't designed to do anything special with them, so they just get ignored by whatever is displaying the data (Internet Explorer, for instance). You'll notice that your message here has suffered the same fate.

The workaround is for you to replace the leading "<" in each case with "<" - this will work fine in the output file and IntelliSense, though of course, it looks awful in the original code.

I have tried various changes to the stylesheet, but unfortunately nothing I've tried has worked so far, so for the moment, that's all I can suggest. I'll look into it further and post a solution here if I find one.

Re: Useful but something's missing

TheOF

1:52 18 Feb '07

Thanks for your kind and prompt reply. However your reply reads 'replace evry "<" with "<"' . I needed a colleague's help to realize ("View Source") that you meant 'replace every "<" with "&-l-t-;" (remove the dashes). It worked - thanks.
Sign In·View Thread·Permalink

Re: Useful but something's missing

Emma Burrows

21:50 18 Feb '07

TheOF wrote: However your reply reads 'replace evry "<" with "<"' . I should have thought of that given the way the forum interprets HTML code. I'm glad your colleague worked it out for you, and of course very pleased to hear that it worked! Thanks for the feedback.
Sign In·View Thread·Permalink

Doxygen

Tim Whitehead

9:27 17 Oct '06

Another feasible solution is called Doxygen http://www.stack.nl/~dimitri/doxygen/ It generates HTML. The primary use for doxygen is for C projects, but they have partially extended it for CSharp projects. This package works at a source code level, as opposed to a compiled IL level like SandCastle.
Sign In·View Thread·Permalink	2.00/5 (1 vote)

Great Article!

Craig C.

11:50 18 Sep '06

Just what I needed to generate some text for a Technical Design Document. It was pretty easy to modify your XSL stylesheet to return what I wanted.

One thing I found that you might want to add is some sorting. I found that by putting <xsl:sort select="@name" data-type="text" order="ascending"/> after every For-Each and every apply-template; the methods, parameters, fields, etc all came out sorted. It was a big help to me anyway.

Craig C.

C code. C code run. Run code run!

Convenient

pgazz

4:24 18 May '06

This is very convenient. It allowed me to make some quick documentation. I'm suprised Visual Studio doesn't have something to generate documentation in HTML or Text or whatever (instead of just intellisense), or does it...?
Sign In·View Thread·Permalink

Re: Convenient

Emma Burrows

4:44 18 May '06

I don't know if there's anything inbuilt - nothing jumped out at me when I wanted something similar, which is why I designed this template. I'm glad to hear that it was useful!
Sign In·View Thread·Permalink

VS 2005

Jazz Soft

6:42 6 Mar '06

Hi Emma, I am using Visual Studio 2005 with '/doc' option. I downloaded your 'Documentation.xsl', then added 'xml-stylesheet' description. I opened XML, but I can't see anything on my browser (IE6). Is your XSL file working with VS2005 correctly?
Sign In·View Thread·Permalink	2.00/5 (1 vote)