title: Generate HTML documentation from XSD using Maven plugin
body: <p>After days of searching, I have yet to find a decent HTML generator that I can use as a Maven reporting plugin. I've tried using JAXB and Javadoc, but it is not really a clean solution, since it forces me to use jaxb-javadoc tags and what's worse, it forces me to duplicate the documentation that is already present. </p>
  
  <p>My comments look like this: </p>
  
  <pre><code>&lt;xs:annotation&gt;
    &lt;xs:documentation&gt;My comments&lt;/xs:documentation&gt;
  &lt;/xs:annotation&gt;
  </code></pre>
  
  <p>I'd rather not use <code>&lt;xs:appinfo&gt;</code> tags if I can avoid it. </p>
  
  <p>I don't want to install a tool/application on a specific machine to generate HTML. I am willing to use the JAXB and Javadoc approach as last-ditch effort, but it's <strong>not</strong> picking up comments unless they are tagged as:</p>
  
  <pre><code>&lt;xs:annotation&gt;
    &lt;xs:appinfo&gt;
      &lt;jxb:class&gt; &lt;!-- Or :property --&gt;
        &lt;jxb:javadoc&gt;My comments&lt;/jxb:javadoc&gt;
      &lt;/jxb:class&gt;
    &lt;xs:appinfo&gt;
  &lt;/xs:annotation&gt;
  </code></pre>
  
  <p>which is ugly and it doesn't seem to work for XSD groups (I've tried both <code>&lt;jxb:class&gt;</code> and <code>&lt;jxb:property&gt;</code>).</p>
  
  <p>Is there any Maven reporting plugin out there that can do this for me? I am also willing to use Xalan or some other transformation framework (as long as it is through Maven), but I am not that keen on creating the stylesheet myself. </p>
  
  <p>Any tips out there?</p>
  
  <p>What I’m looking for is to simply abstract XML Schema elements as messages, which is most often the case for RESTful-WS (as an example). Generating HTML documentation which allows application developers, laymen and business developers to share a common knowledge base to understand a protocol or API. None of these are interested in the finer points of XML Schemas (targets, QNames, namespaces, etc), they just want to know:</p>
  
  <ul>
  <li>What does request X look like (an XML element)? </li>
  <li>What fields can/must I set (max/minOccurs)?</li>
  <li>What information is available in response Y?</li>
  <li>For a restricted field, what enum values are allowed?</li>
  </ul>
  
  <p>Javadoc goes a long way to answer these questions, but in order for JAXB to pick it up, the XSD must be tagged in a certain way (using appinfo tags), as well as polluting the original XSD with JAXB namespace. By the way, I generate both C, C++ and Java bindings from the XSD, so the XSD is the master document.</p>
  
  <p>WADL doesn’t quite fit the bill here because even that is too technical and its purpose is mainly to be consumed by machines, not people. </p>
  
  <p>Apart from maybe changing a color schema in the generated HTML, I was baffled to learn that there isn’t a turnkey solution for this. Almost all of them require a local installation of some sort (apart from the JAXB and Javadoc Maven plugin I use now) which goes against the grain of Maven’s concept of portable builds. All organizations I worked for have either made their peace with JAXB/Javadoc or simple developed their own transformation tool to generate HTML.</p>