How to convert xsd to human readable documentation?

Question

We have several XML-based interfaces that are well documented in XSD schemas. The interfaces will now be publicly available, and we would like to create reference documentation for them.

Is there a tool that can automatically convert XSD files to some more readable format?

Answer 1

xs3p can do what you want (see also their SourceForce page ).

Answer 2

Insert it at the top of the XSD

<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="xs3p.xsl"?> 

You can then directly view the XSD file using a web browser. The web browser performs the conversion to HTML using the specified XSLT.

You do not need an XSL processor, but style sheets such as xs3p will not generate links using this approach. I am using Firefox web browser, IE8 seems to be useless for this.

I 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.

Answer 3

oXygen has a very good tool for documenting the XSD schema, which makes it easy to configure parameters 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 one of the other answers, XSD is just an XML file, so you can create your own XSLT to create any document that you like.

Answer 4

An XSLT script can do the job.

Answer 5

Most likely, you do not want to use a common tool to document your schema. Schema documentation tools (I'm most familiar with what XML espionage has) are for reading schemas. From your description, this does not sound the way you want; You want to use the information in your schema as the basis for software documentation.

When I needed to do this, the approach I took was to develop HTML that looked like I needed the documentation to view, and then figure out what information in the diagram I would need to capture in order to fill it. Using this as a template, it is quite simple to derive relevant information from the schema using XSLT.

Answer 6

In the past, I generated documentation using a tool I found on Freshmeat.net called xsddoc . Having looked at it now (to get a direct link), I see that its developers have been replaced by the xnsdoc tool. The novelty is free for use by open source projects, but if you use it for a commercial product, you may have to license it. If the latest version released under the "xsddoc" banner is suitable for your purposes, you can simply use it.

The documentation that it produces has a Javadoc appearance and allows some degree of control in the stylesheet, etc.

Answer 7

If you are ready to delve into the intricacies of Sandcastle , I highly recommend the XML Schema Documenter , which is a plugin for the excellent Sandcastle Help File Builder .

The possible outputs are the same as Sandcastle: website, HTML help file (CHM), MS Help 2 content, MS Help Viewer 1 ...

Answer 8

You should not try to convert it (or write it in advance) into a docbook .