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?
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.
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 FlexDoc/XML is an XML documentation tool with an XSD documentation component called XSDDoc that looks interesting.
Of course, 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.
