Generating documentation for an XML Schema

<oXygen/> can generate detailed documentation for the components of an XML Schema in HTML, PDF and DocBook XML formats similar with the Javadoc documentation for the components of a Java class. You can select the components and the level of detail. The components are hyperlinked in both HTML and DocBook documents.

To generate documentation for an XML Schema document use the dialog Schema Documentation. It is opened with the action ToolsGenerate DocumentationSchema Documentation... (Ctrl+Alt+S). It can be also opened from the Project view contextual menu: Generate DocumentationSchema Documentation... The dialog enables the user to configure a large set of parameters for the process of generating the documentation.

 

Figure 4.53. The Output panel of the Schema Documentation dialog

The Output panel of the Schema Documentation dialog

The Schema URL field of the dialog panel must contain the full path to the XML Schema (XSD) file you want to generate documentation for. The schema may be a local or a remote one. You can specify the path to the schema using the editor variables.

You can choose to split the output into multiple files by namespace, location or component.

You can export the settings of the Schema Documentation dialog to an XML file by pressing the "Export settings" button. With the exported settings file you can generate the same documentation from the command line

 

Figure 4.54. The Settings panel of the Schema Documentation dialog

The Settings panel of the Schema Documentation dialog

When you generate documentation for a schema you can choose what components to include in the output (global elements, global attributes, local elements, local attributes, simple types, complex types, group, attribute groups, referenced schemas, redefines) and the details to be included in the documentation:

These options are persistent between sessions.

 Generate documentation in HTML format

The HTML documentation contains images corresponding to the schema definitions as the ones displayed by the schema diagram editor. These images are divided in clickable areas which are linked to the definitions of the clicked names of types or elements. The documentation of a definition includes a Used By section with links to the other definitions which refer to it. If the Escape XML Content option is unchecked, the HTML or XHTML tags used inside the xs:documentation elements of the input XML Schema for formatting the documentation text (for example <b>, <i>, <u>, <ul>, <li>, etc.) are rendered in the generated HTML documentation.

The generated images format is PNG. The image of an XML Schema component contains the graphical representation of that component as it is rendered in the Schema Diagram panel of the <oXygen/>'s XSD editor panel.

 

Figure 4.55. Schema documentation example

Schema documentation example


The generated documentation include a table of contents. The contents can be grouped by namespace, location or component type. After the table of contents there is presented some information about the main schema, the imported, included and redefined schemas. This information consists in the schema target namespace, the schema properties (attribute form default, element form default, version) and the schema location.

 

Figure 4.56. Information about a schema

Information about a schema


If you choose to split the output into multiple files, the table of contents will be displayed in the left frame. The contents will be grouped in the same mode. If you split the output by location, each file contains a schema description and the components that you have chosen to include. If you split the output by namespace, each file contains information about schemas from that namespace and the list with all included components. If you choose to split the output by component, each file will contain information about a schema component.

After the documentation is generated you can collapse details for some schema components. This can be done using the Showing view

 

Figure 4.57. The Showing view

The Showing view


For each component included in the documentation the section presents the component type follow by the component name. For local elements and attributes the name of the component is specified as parent name/component name. You can easily go to the parent documentation by clicking on the parent name.

 

Figure 4.58. Documentation for a schema component

Documentation for a schema component