CodeProject: Simple XSLT stylesheet for Visual Studio .NET XML documentation. Free source code and programming help

Report Article

Discuss

Send to a friend

24 votes for this Article.

Popularity: 6.31 Rating: 4.58 out of 5

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

Emma's first steps in programming took place at primary school over twenty 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.

Emma is currently expecting another baby after taking a break to have a first baby. Some day, perhaps when both babies have gone to university, she hopes to improve her C# and web development skills and, of course, write more articles for Code Project.

Occupation:	Web Developer
Location:	United Kingdom

Other popular XML articles:

C# and XML Source Code Documentation
Demonstrates how to use C#.NET's XML source documentation to produce professional, indexed and searchable source documentation.
Sending Files in Chunks with MTOM Web Services and .NET 2.0
How to send large files across web services in small chunks using MTOM (WSE 3)
Microsoft Office XML formats ? Defective by design
Case studies why Microsoft Office XML formats are broken
Load and save objects to XML using serialization
A C# program to demonstrate loading and saving an object to an XML file using XML serialization encapsulated in a wrapper class.
XmlSerializer and 'not expected' Inherited Types
A solution to XmlSerializing inherited types not known until runtime.

Article Top

You must Sign In to use this message board.

Msgs 1 to 25 of 29 (Total in Forum: 29) (Refresh)

FirstPrevNext

Just what I was looking for

norsemonster

12:38 29 Oct '08

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

very usefull

gdeenen

0:58 27 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

16:00 3 Jun '08

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

MohsenElahi

14:19 18 Mar '08

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

XML comments : shortcoming

aliascodeproject

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

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

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

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

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

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

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

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

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

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

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

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

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

Re: VS 2005

kc1337

0:42 22 Aug '06

It's working fine here ... with a little modification, though. I deleted the top blank line in the stylesheet file after getting errors in Opera and Firefox. I also noticed that to be able to see the methods within a class, I needed to at least add summary tags to the class itself. Hope it helps.
Sign In·View Thread·PermaLink	3.00/5 (3 votes)

Comments after <?xml... in FireFox...

StuFF mc

3:46 12 Sep '05

Hi ! Nice job I wanted to see it in FireFox and it told me XML Parsing Error: xml processing instruction not at start of external entity Location: file:///D:/TP5/Projects/TpCommunicator/TpCommunicator/Documentation.xsl Line Number 6, Column 1: I just had to put your " don't remove this header " After the first line. Internet Explorer, as usual, is not as strict, and allow comments before
Sign In·View Thread·PermaLink

Re: Comments after <?xml... in FireFox...

Emma Burrows

4:14 12 Sep '05

Thanks for the info - I must admit my PC is Microsoft-dominated, so I didn't know that could be a problem. I hope the stylesheet will prove useful for whatever "TpCommunicator" is.
Sign In·View Thread·PermaLink

How to use attribute to be a condition?

mathuros_paiboon

6:47 18 Jul '05

Hello

      Can someone help me! I have a problem about xslt I want to use attribute to be a condition what should I write xslt command or function
this is my xml file

<assess_controls>
      <assess_control>
            << b>company_name</b>> <u>xxx</u></company_name>
            << b>form_name</b> <b>no</b>="<u>1</u>">form_xxx</form_name>
            <assesser_name>xxx</assesser_name>

            <control_type>xxx</control_type>

            <control_subgroup sub_group="1 xxx">
                  <activitys>
                        <activity>xxx</activity>
                        <comment>comment 1</comment>
                  </activitys>
            </control_subgroup>
            <control_subgroup sub_group="2 xxx">
                  <activitys>
                        <activity>xxx3 </activity>
                        <comment>comment 3</comment>
                  </activitys>
            </control_subgroup>
      </assess_control>
            <assess_control>
            <company_name>xxx</company_name>
            <form_name no="2">form_xxx</form_name>
            <assesser_name>yyy</assesser_name>

            <control_type>yyy</control_type>

            <control_subgroup sub_group="1 yyy">
                  <activitys>
                        <activity>yyy</activity>
                        <comment>comment 1</comment>
                  </activitys>
            </control_subgroup>
            <control_subgroup sub_group="2 yyy">
                  <activitys>
                        <activity>yyy3 </activity>
                        <comment>comment 3</comment>
                  </activitys>
            </control_subgroup>
      </assess_control>
</assess_controls>

<big>I want to use <company_name>, <form_name> and   attribute of form_name "no"
and xslt if below</big>

      <xsl:param name="<b>comp</b>">admin</xsl:param>
      <xsl:param name="<b>formname</b>">pppp</xsl:param>
      <xsl:param name="<b>formno</b>">1</xsl:param>

   <xsl:template match="/">
      <HTML>
         <body STYLE="font-family:Arial, helvetica, sans-serif; font-size:10pt;
                  background-color:#EEEEEE">

            <xsl:apply-templates/>

         </body>
      </HTML>
</xsl:template>

<xsl:template match="assess_control">
<xsl:if test="company_name = <b>$comp</b>">
      <xsl:if test="form_name = <b>$formname</b>">

      <xsl:apply-templates select= "form_name"/>

         <table class = "borders" border = "1">
                              <tr class = "largebluetext">
                              <td><xsl:value-of select="company_name"/></td>
                              <td><xsl:value-of select="control_type"/></td>
                              <td><xsl:value-of select="control_group"/></td></tr>
                              <tr><td><xsl:value-of select ="form_name"/></td></tr>
         </table>

                  <xsl:apply-templates select ="control_subgroup "/>
            <xsl:value-of select="@sub_group"/>
      </xsl:if>
</xsl:if>
</xsl:template>
<xsl:template match="form_name">
      <xsl:if test="<b>$formno</b>">
            <table><tr><td>no: <xsl:value-of select="@no"/></td></tr></table>
      </xsl:if>
</xsl:template>

<xsl:template   match="control_subgroup">
<span class="blacktext">   <xsl:value-of select="@sub_group"/>   </span>
<xsl:for-each select="activitys">
      <table class = "borders" border = "1">
            <tr class = "largeyellowtext">
            <td class = "borders1"><xsl:value-of select="activity"/></td>
            <td class = "borders2"><xsl:value-of select="score"/></td>
            <td class = "borders3"><xsl:value-of select="comment"/></td></tr>
      </table>
</xsl:for-each>
</xsl:template>

</xsl:stylesheet>

The problem is I can't specify form_name[@no] I want.
What wrong of my xslt code?

Thank you very much

Thanks

dcbrower

3:10 10 Mar '05

Just what I need to get me started documenting my code.
Sign In·View Thread·PermaLink

Re: Thanks

RGB_VSL

0:58 9 Jan '07

Just like to add my thanks too. Turned the documentation from a heap of ugly tags to a nice bit of text.
Sign In·View Thread·PermaLink

NDoc

maharishi_b

18:22 28 Feb '05

I admit that u have done a wonderful work but its too basic and cumbersome. Have u ever tried NDoc utility... it gives u documentation based on MSDN design or Javadoc design anything that u r comfortable with.

the link for the site is:

NDoc

NDoc generates class library documentation from .NET assemblies and the XML documentation files generated by the C# compiler (or with an add-on tool for VB.NET).

NDoc uses pluggable documenters to generate documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-online style web pages.

If you're new to NDoc, the Programmer's Reference provides an example of NDoc's output.

NDoc's source code is freely available under a certified Open Source license. We welcome everyone to use our software in the hopes that they can provide feedback, submit bug reports and fixes, or even join us as a developer!

thanxs

Maharishi

Nothing is Impossible. Even impossible spells "i m possible"

5.00/5 (1 vote)

Re: NDoc

Emma Burrows

4:20 1 Mar '05

maharishi_b wrote:
I admit that u have done a wonderful work but its too basic and cumbersome. Have u ever tried NDoc utility... it gives u documentation based on MSDN design or Javadoc design anything that u r comfortable with.

I did actually see some references to NDoc while I was looking for a ready made XSLT stylesheet. It looks very useful for generating actual professional documentation. But all I wanted was a very basic way of doing a quick transformation of the XML into something more legible without actually converting it into another document format. So I think the two solutions cater for quite different needs.

Thanks for the feedback and the link; I'm sure it'll be useful for people who need something more sophisticated.

Last Visit: Tuesday, December 2, 2008 2:06 AM Last Update:Tuesday, December 2, 2008 2:06 AM

1 Next »

General News Question Answer Joke Rant Admin