XSD documentation as a part of build process

Question

I've got multiple XSD files describing a schema. I'd like to generate a human readable documentation as a result of a build process.

The XSD is maintained and review within repository (gitflow) and commiting the documentation makes the repository cluttered. I'd like to generate human readable HTML during the build process (maven / gradle / ant build or simple CLI interface)

Found this post How to convert xsd to human readable documentation? and DocFlex/XML Maven plugin seems interesting but I can't believe that's the only one.

Any helpful tips on that?

Further research: oxygen XML has command line tools: http://www.oxygenxml.com/doc/versions/17.0/ug-editor/#topics/documentation-XML-Schema-command-line.html which generates desired HTML files. Still it's not integrated with build tools in any way (all manual work) — Jakub Marchwicki, Aug 21 '15 at 21:08
You should add your edit as an answer (and accept it), to make it easier to see this solution and to know that you consider the question answered and resolved. — Mads Hansen, Aug 26 '15 at 01:06

score 1 · Accepted Answer · answered Aug 26 '15 at 21:15

I ended up with Oxygen Editor schemaDocumentation.sh script wrapped in gradle build.

My build.gradle so far looks like this - and I suspect it's still work in progress. It does it's job, HTMLs get generated to build/generated-html folder, but it requires oxygen to be installed in OXYGEN_HOME bath (with license included). I may fix it someday in the future

apply plugin: 'java'

version = "1.0-SNAPSHOT"

ext {
    generatedDir = new File(buildDir, "generated-html")
}

def OXYGEN_HOME = "/opt/java/oxygen"
def schemaFiles = ["page", "metadata"]

schemaFiles.each { pageName -> 
    task "${pageName}SchemaTask"(type: JavaExec) {
        mkdir generatedDir

        classpath = files([
            "$OXYGEN_HOME", 
            "$OXYGEN_HOME/classes", 
            "$OXYGEN_HOME/lib", 
            "$OXYGEN_HOME/lib/oxygen.jar", 
            "$OXYGEN_HOME/lib/oxygenDeveloper.jar", 
            "$OXYGEN_HOME/lib/fop.jar", 
            "$OXYGEN_HOME/lib/xmlgraphics-commons-1.5.jar", 
            "$OXYGEN_HOME/lib/batik-all-1.7.jar", 
            "$OXYGEN_HOME/lib/xercesImpl.jar", 
            "$OXYGEN_HOME/lib/xml-apis.jar", 
            "$OXYGEN_HOME/lib/org.eclipse.wst.xml.xpath2.processor_1.2.0.jar", 
            "$OXYGEN_HOME/lib/icu4j.jar", 
            "$OXYGEN_HOME/lib/saxon.jar", 
            "$OXYGEN_HOME/lib/saxon9ee.jar", 
            "$OXYGEN_HOME/lib/log4j.jar", 
            "$OXYGEN_HOME/lib/resolver.jar", 
            "$OXYGEN_HOME/lib/oxygen-emf.jar", 
            "$OXYGEN_HOME/lib/commons-httpclient-3.1.jar", 
            "$OXYGEN_HOME/lib/commons-codec-1.3.jar", 
            "$OXYGEN_HOME/lib/commons-logging-1.0.4.jar", 
            "$OXYGEN_HOME/lib/httpcore-4.3.2.jar", 
            "$OXYGEN_HOME/lib/httpclient-cache-4.3.5.jar", 
            "$OXYGEN_HOME/lib/httpclient-4.3.5.jar", 
            "$OXYGEN_HOME/lib/fluent-hc-4.3.5.jar", 
            "$OXYGEN_HOME/lib/httpmime-4.3.5.jar", 
            "$OXYGEN_HOME/lib/commons-logging-1.1.3.jar", 
            "$OXYGEN_HOME/lib/commons-codec-1.6.jar"
        ].toList())
        main = 'ro.sync.xsd.documentation.XSDSchemaDocumentationGenerator'  
        jvmArgs = ["-Djava.awt.headless=true"]
        args = ["schema/${pageName}.xsd", "-format:html", "-split:location", "-out:$generatedDir/${pageName}.html"] 
    }   
}

task schema(dependsOn: tasks.matching { Task task -> task.name.endsWith("SchemaTask")}) {
}

defaultTasks 'schema'

I've documented the whole approach to build docs from XSD in the build process in this post http://jakub.marchwicki.pl/posts/2015/08/26/get-your-xsd-docs-as-build-process/

XSD documentation as a part of build process

1 Answers1