XSD文档作为构建过程的一部分

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?

Answer 1

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/