How to convert xsd to human readable documentation? [closed]

Question

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?

Derogate

If I wasn't 2 years late, I would say 'close' because it's a duplicate of #202549 – Christo

Answer 1

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

Ilyssa

Wow, amazed at the votes, maybe because there are so few alternatives, but the output from x3sp is incredibly ugly and hard to follow - just reading the plain xsd is much easier. And what's with the "AusAddress" type randomly appended to the end? – Menzies

The linked page does not seem to exist any more, and I cannot find any traces of a software named x3sp at least with a quick web search. – Pokelogan

@O.R.Mapper - that is because the letters/numbers are in the wrong order – Ramsay

"AusAddress" is part of the legend, you can turn it off in the settings, see printLegend in the xsl file. – Rubio

Answer 2

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.

Knobby

To clarify: modern web browsers (such as Firefox) have a built-in XSLT processor allowing for these transformation to occur, so the reliability of this approach depends on the runtime environment. – Provisory

don't know about IE8 - but IE11 works fine with one caveat, I can't seem to get it to work by dropping the XSD file on it. However, if the file is served through a webserver it works fine... when I hit the IE button in intellij IDEA while viewing the XSD, it sends it through localhost - so it renders correctly.Saves me the hassle of installing firefox. Since chrome won't work for me.My ultimate dream would be to find something like x3sp - but that doesn't jumble the documentation all together... rather, leave it in the same position that it was in the XSD (under the element it was placedafter) – Norther

Answer 3

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.

Joettejoey

Answer 4

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.

Scummy

Answer 5

An XSLT script can do the job.

Dorina

Answer 6

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.

Translocation

Answer 7

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

Dignadignified

Answer 8

It's should not be to hard to convert it (or write in advance) to docbook format.

Gaulish

Not sure how referencing a book comes close to answering this question. – Interlocution

Docbook is not a book rather a tool that can help convert XML to Html/word/pdf format. Per my understanding, it's much more concrete than just referring to XSLT transformation. – Gaulish