Generating Documentation for an XML Schema

Oxygen XML Editor can generate detailed documentation for the components of an XML Schema in HTML, PDF, DocBook, or other custom formats. You can select the components and the level of detail. The components are hyperlinked in both HTML and DocBook documents.

Note: You can generate documentation for both XML Schema version 1.0 and 1.1.

To generate documentation for an XML Schema document, select XML Schema Documentation from the Tools > Generate Documentation menu or from the Generate Documentation submenu in the contextual menu of the Project view.

Figure: The XML Schema Documentation Dialog Box

The Schema URL field of the dialog box must contain the full path to the XML Schema (XSD) file for which you want to generate documentation. The schema may be a local or a remote file. You can specify the path to the schema by entering it in the text field, or by using the Insert Editor Variables button or the options in the Browse drop-down menu.

The Output Tab

The following options are available in the Output tab:

Format - Allows you to choose between the following formats:
- HTML - The documentation is generated in HTML output format.
- PDF - The documentation is generated in PDF output format.
- DocBook - The documentation is generated in DocBook output format.
- Custom - The documentation is generated in a custom output format, allowing you to control the output. Click the Options button to open a Custom format options dialog box where you can specify a custom stylesheet for creating the output. There is also an option to Copy additional resources to the output folder and you can select the path to the additional Resources that you want to copy. You can also choose to keep the intermediate XML files created during the documentation process by deselecting the Delete intermediate XML file option.
Output file - You can specify the path of the output file by entering it in the text field, or by using the Insert Editor Variables button or the options in the Browse drop-down menu.
Split output into multiple files - Instructs the application to split the output into multiple files. You can choose to split them by namespace, location, or component name.
Open in Browser/System Application - Opens the result in the system application associated with the output file type.
Note: To set the browser or system application that will be used, open the Preferences dialog box, then go to Global and set it in the Default Internet browser field. This will take precedence over the default system application settings.
Keep only the annotations with xml:lang set to - The generated output will contain only the annotations with the xml:lang attribute set to the selected language. If you choose a primary language code (for example, en for English), this includes all its possible variations (en-us, en-uk, etc.).

The Settings Tab

When you generate documentation for an XML schema you can choose what components to include in the output and the details to be included in the documentation.

Figure: The Settings Tab of the XML Schema Documentation Dialog Box

The Settings tab allows you to choose whether or not to include the following components: Global elements, Global attributes, Local elements, Local attributes, Simple Types, Complex Types, Groups, Attribute Groups, Redefines, Referenced schemas, Include notations.

You can choose whether or not to include the following other details:

Diagram - Displays the diagram for each component. You can choose the image format (JPEG, PNG, GIF, SVG) to use for the diagram section. The generated diagrams are dependent on the options from the Schema Design Properties page.
- Diagram annotations - This option controls whether the annotations of the components presented in the diagram sections are included.
Namespace - Displays the namespace for each component.
Location - Displays the schema location for each component.
Type - Displays the component type if it is not an anonymous one.
Type hierarchy - Displays the types hierarchy.
Model - Displays the model (sequence, choice, all) presented in BNF form. Different separator characters are used depending on the information item used:
- xs:all - its children will be separated by space characters.
- xs:sequence - its children will be separated by comma characters.
- xs:choice - its children will be separated by | characters.
Children - Displays the list of component's children.
Instance - Displays an XML instance generated based on each schema element.
Used by - Displays the list of all the components that reference the current one. The list is sorted by component type and name.
Properties - Displays some of the component's properties.
Facets - Displays the facets for each simple type
Identity constraints - Displays the identity constraints for each element. For each constraint there are presented the name, type (unique, key, keyref), reference attribute, selector and field(s).
Attributes - Displays the attributes for the component. For each attribute there are presented the name, type, fixed or default value, usage and annotation.
Asserts - Displays the assert elements defined in a complex type. The test, XPath default namespace, and annotation are presented for each assert.
Annotations - Displays the annotations for the component. If you choose Escape XML Content, the XML tags are present in the annotations.
Source - Displays the text schema source for each component.
Generate index - Displays 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.
- Include resource hierarchy - Specifies whether the resource hierarchy for an XML Schema documentation is generated.

Export settings - Save the current settings in a settings file for further use (for example, with the exported settings file you can generate the same documentation from the command line interface.)

Load settings - Reloads the settings from the exported file.

Generate - Use this button to generate the XML Schema documentation.