DocFlex/XML - XML Schema Documentation Generator and Toolkit

A powerful multi-format XML schema (XSD) documentation generator and a tool for rapid development of custom XSD documentation generators according to user needs.

About DocFlex/XML

DocFlex/XML is a Java-based software system for development and execution of high performance template-driven documentation generators from any data stored in XML files.

The actual doc/report generators are programmed in the form of special templates using a graphic Template Designer that represents the templates visually in a form resembling the output they generate. Further, the templates are interpreted by a Template Processor, which takes on input the XML files and produces by them the result documentation.

This article describes an application of DocFlex/XML for the task of generation of high-quality XML schema documentation. That includes the following features of DocFlex/XML system:

  1. "XSDDoc" template set that implements the ready-to-use XML schema documentation generator itself.
  2. Template Processor makes the templates work. Currently, it provides three interchangeable output generators for HTML, RTF, TXT (plain text) formats.
  3. Template Designer provides a high quality GUI to design/modify templates. If you need a special XML schema doc generator, the simplest way to create it is to modify the standard XSDDoc templates. The template designer enables you to do that.
  4. Integrations with Altova XMLSpy and Oxygen XML Editor. If you are a user of one of those popular XML editors, you can turn it also into a dynamically linked diagramming engine for DocFlex. That will allow you to include automatically the XSD diagrams generated by XMLSpy/OxygenXML into the XML schema documentation generated by DocFlex (with the full support of hyperlinks).

"XSDDoc" Template Set

It is the implementation of XML schema documentation itself, which provides the following functionality:

Template Processor

The template processor (also called simply "generator") makes everything work. It consists of two logical parts:
  1. Template Interpreter
  2. Output Generator
The output generator actually has three different implementations for each currently supported output format: HTML, RTF, TXT (plain text). The plain-text output can be used to generate documentation in formats not supported directly by DocFlex.

The template processor is started directly from Java command line with the following arguments:

Actually, the number of settings may be so large that the template processor provides a special GUI to specify everything interactively (click to enlarge):

Template Designer

Although DocFlex templates are stored as plain-text files (with an XML-like format), they are not supposed for editing manually. Rather, a special graphic Template Designer must be used, which visualizes the templates in the form of template components they are made of. Those components are the actual constructs of the template language (not some textual statements, operators, blocks etc.)

The following screenshots show templates open in the Template Designer (click to see a lot more):

That approach has a number of advantages, among them:

Integrations

Generation of XSD diagrams

DocFlex/XML is able to work with any kind of diagrams (i.e. inserting them automatically in the generated output). That is supported on the level of templates, along with the generation of hypertext imagemaps, as shown on the following screenshot (click to see a lot more):
DocFlex/XML provides no diagramming engine of its own. Instead, it includes integrations with two most popular XML editors that do generate XSD diagrams: Effectively, the third-party software is used as a dynamically linked diagramming engine. The advantage of such integrations is that when you are the user of one of those XML editors, you will get in the documentation generated by DocFlex the same diagrams as you see in your XML editor.

Here is how such a documentation with diagrams looks (click on a screenshot to view the real HTML):

Apache Ant & Maven

As a pure Java application, DocFlex/XML can be run in any environment that runs Java itself.

The template processor can be easily integrated with Ant (that can be specified just in the Ant build file). In case of Maven, DocFlex/XML includes a simple Maven plugin. It is possible also to use also all diagraming integrations with both Ant and Maven.

Links

DocFlex/XML (home page):   http://www.filigris.com/docflex-xml/
DocFlex/XML XSDDoc:   http://www.filigris.com/docflex-xml/xsddoc/
XSDDoc Examples:   http://www.filigris.com/docflex-xml/xsddoc/examples/
XMLSpy Integration:   http://www.filigris.com/docflex-xml/XMLSpy/
OxygenXML Integration:   http://www.filigris.com/docflex-xml/OxygenXML/
Free downloads:   http://www.filigris.com/downloads/
This original article:   http://www.filigris.com/ann/docflex-xsd/