Documenting XSLT files

Jul 7, 2008 at 12:51 AM
I just downloaded and run a couple of quick proof of concept projects and really like what I saw.  Of course as soon as a developer see something they like they want more.

A large portion of our project is in XSLT.  I can write an XSLT to produce the documentation I want from the production XSLT files.  However, I do not know which of the XSD formats to use to integrate with sandcastle.

I am sure that at some future point I will be asking how to automate the production of the documentation, but for know I would just like to know how to produce pieces that will fit in.


Jul 7, 2008 at 4:47 AM

Hi Greg,

So you have XSLT files and you'd like to produce HTML documentation for them using Sandcastle?

The three presentation styles that come with Sandcastle are designed to build HTML documentation for application programming interfaces (APIs).  Technically, they are designed only for managed APIs, but they can also be used to document other platforms as well, such as AJAX, for example.

If you want to document XSLT using the three built-in presentation styles then you must:

  • Generate a file that uses the same schema that is used when reflecting into managed APIs.  (The schema is located in Sandcastle's Schemas\Reflection folder.)
  • Generate an XML documentation file that uses the same schema as the compiler-generated XML documentation files that contain code comments.

I can't say whether XSLT will fit nicely into the existing schema that Sandcastle requires, but it's doubtful.  In this case you'd have to roll your own solution by creating a custom presentation style.

Basically you'd have to write a program that could parse information about the structure and entities in an XSLT file and also any comments that you'd like included in the HTML documentation.  From here the process would be similar to building documentation for managed APIs, although you'd have to use custom XSL files for your presentation style that could produce the HTML documentation from the XSLT "reflection" information.  A custom Build Assembler configuation file would need to be created as well.

If you plan on trying this out I suggest starting with an existing presentation style by copying it to another directory.  Then modify its parts, starting with the XSL transformations that produce the final HTML documentation.  Once you determine what the final documentation should look like you can infer the schema for the XSLT reflection information and the XML documentation.

- Dave

Jul 7, 2008 at 5:17 AM
>>Greg: However, I do not know which of the XSD formats to use to integrate with sandcastle.
A simple way that will give you more control over the formating is to use the conceptual help topic,
in particular there is developerXmlReference topic type.
The developerXmlReference topic type currently as some issues but we could help you through the
Sandcastle Styles effort to resolve them.

>>Greg...future point I will be asking how to automate the production of the documentation.
I am also working/researching on automating the documentations of XSD. The priority is, however, low
(compared to the other work I am doing with Sandcastle through the Sandcastle Assist effort) mainly because
I do not have a project immediately requiring this. I could coordinate with you to find a reusable solution, if required.

Best regards,