We have a few XML based interfaces that is quite well documented in XSD schemas. The interfaces are now going to be publicly available and we would like to create reference documentation for them.
Is there a tool that can automatically convert XSD files into some more readable format?
oXygen has very nice XSD schema documentation tool that allows for easy customization through options and additional CSS files.
I haven't used it before, but DocFlex/XML is an XML documentation tool with an XSD documentation component called XSD Doc that looks interesting.
Of couse, as pointed out in on of the other answers, XSD is just an XML file so a custom XSLT could be written to generate any documentation output you like.
The odds are pretty good that you don't want to use a generic tool for documenting your schema. Schema documentation tools (I'm most familiar with the one in XML Spy) are designed to make schemas readable. From your description, it sounds like that's not really what you want; what you want is to use the information in your schema to as the basis of software documentation.
When I've needed to do this, the approach I took was to design HTML that looked the way I needed the documentation to look, and then figure out what information in the schema I'd need to grab to populate it. Using that as a template, it's pretty straightforward to pull in relevant information from the schema using XSLT.
I have generated documentation in the past using a tool I found on Freshmeat.net called xsddoc. Looking it up just now (to get the direct link), I see that it has been superceded by its developers with a tool called xnsdoc. The newer one is free for use by open-source projects, but if you are using this for a commercial product you may have to license it. If the last version released under the "xsddoc" banner suits your purposes, then you can just use that one.
The documentation it produces has the look and feel of Javadoc, and allows for some degree of control in the stylesheet, etc.
Insert this at the top of the XSD
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="xs3p.xsl"?>
Then you can directly view the XSD file using a web-browser. The web browser does the conversion to HTML using the specified XSLT.
You don't need an XSL processor, but stylesheets like xs3p won't generate links using this approach. I use the Firefox web-browser, IE8 seems useless for this.
I've tried these xsl stylesheets: https://sourceforge.net/projects/xs3p/files/xs3p-1.1.3.zip/download http://crism.maden.org/consulting/pub/xsl/xsd2html.xsl
I think I prefer xs3p.
Hello everybody,
I happen to be a chief architect of the DocFlex/XML XSDDoc tool (see "http://www.filigris.com/products/docflex_xml/xsddoc/") mentioned here by Mads Hansen.
Well, when I read what everybody says here, I'm always thinking the following thoughts -- Computers probably existed yet in Stone Age! Indeed, you can bring a few stones and use them to help yourself with some calculations. That you can call a "computer". You may be even happy and proud of that device!
My point is this. You want to generate an XML schema documentation. But what do you mean under the words "XML schema documentation"? After all, the ultimate XML schema "documentation" is its XML source. I believe, there is no much use of any documentation that shows little more than you can see in the XML schema source by yourself.
In my view, a true XML schema documentation should allow the user to quickly find any necessary meaningful information about the XML schema (more precisely, the XML schema project), if only that information could be automatically obtained or deduced from it.
You cannot achieve that goal just by programming a few XSLT scripts!
XSL is a programming language that was grown from CSS. CSS is used to format HTML documents so as to hold in a single place most of formatting settings shared by several HTML files, thereby reducing their sizes as well as allowing a (rather weak) possibility to customize the overall look & feel. The idea of XSL was to repeat the same trick for generic XML files. But XML was not viewable directly by the web browsers. Therefore, something was needed to somehow transform XML on the fly and make an HTML from it. So, the CSS was extended with some processing constructs that mandatory must have been declarative only, non-procedural ones. Otherwise, it would threaten to become a yet another universal programming language losing its easy-to-use interpreted-on-the-fly features. Later indeed XSL started to be used for increasingly more complex tasks of processing of XML files. Hence, XSL was extended with even more data processing constructs. Yet, that evolution didn't change the light-weight essence of XSL. In a sense, XSL language is too powerful for too big and complex tasks. It is not a database engine, after all!
We invented and implemented our own technology alternative to XSLT, which in fact is not limited to XML. Rather the goal was to make possible processing any imaginable data sources in the way as if they are virtual XML files. XML itself is obviously covered by this. The processing is based on some "templates", which play a role similar to XSLT scripts. Like XSLT scripts, the templates are interpreted by a special processor. But this is not based on XSLT in any way (if only some ideas were borrowed). More details you can read here: "http://www.filigris.com/products/docflex/"
Our XML schema documentation generator called "DocFlex/XML XSDDoc" is based on this technology. It is implemented in the form of a template set that currently consists of 63 templates.
That everything does generate XML schema documentation! See some examples here: "http://www.filigris.com/products/docflex_xml/xsddoc/examples/"
In fact, here you can see how big actually that task is. For comparison, we have developed with the same technology a replacement for the standard Javadoc, which is an automatic documentation generator for Java programs. (Our tool is called DocFlex/Javadoc, see here: "http://www.filigris.com/products/docflex_javadoc/"). You might think that the developing of the original Javadoc was a piece of work. Yet, it took from us to design only a template set made of just 12 template to support almost all what the standard Javadoc does. Our XML schema documentation generator, which is based on the same technology, is more than 5 times bigger that this.
Now, try to implement the same with XSLT!
If you are ready to delve into the intricacies of Sandcastle, I highly recommend XML Schema Documenter which is a plugin for the excellent Sandcastle Help File Builder.
Possible outputs are the same as Sandcastle: a website, a HTML Help (CHM) file, MS Help 2 content, MS Help Viewer 1...