<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 → → . It can be also opened from the Navigator contextual menu: The dialog enables the user to configure a large set of parameters for the process of generating the documentation.
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.
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:
Diagram Show the diagram for each component. You can choose the image format to use for the diagram section.
Diagram annotations The option controls whether or not the annotations of the components presented in the diagram sections should be included.
Namespace Show the namespace for each component.
Location Show the schema location for each component.
Type Show the type of the component if it is not an anonymous one.
Type hierarchy Show the types hierarchy
Model Show the model (sequence, choice, all) presented in BNF form. form. For xs:all the model the children are separated by space. For xs:sequence the children are separated by comma, for xs:choice by |. You can easily check if an element is required or optional.
Children Show the list of all the children of the component
Instance Show an XML instance generated based on each schema element.
Used by Show the list of all the components that refer the component sorted by component type and name.
Properties Show some properties for the component.
Facets Show the facets for each simple type
Identity constraints Show the identity constraints for each element. For each constraint there are presented the name, the type (unique, key, keyref), the refer attribute, the selector and field(s).
Attributes Show the attributes for the component. For each attribute there are presented the name, the type, the fixed or default value, the use and annotation.
Annotations Show the annotations for the component. If you choose Escape XML Content, the XML tags are present in the annotations.
Source Show the text schema source for each component.
Generate index Create an index with the components included in the documentation.
Include local elements and attributes If checked, local elements and attributes are included in the documentation index.
These options are persistent between sessions.
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.
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.
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
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.