Generating Documentation for an XML Schema
To generate documentation for an XML Schema document, select XML Schema
Documentation from the menu or from the Generate
Documentation submenu in the contextual menu of the Project
view. You can also open
the tool by using the 
Generate Documentation toolbar button.
The Schema URL field of the dialog box must contain the full path to
the XML Schema (XSD) file that will have documentation generated. 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.
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.
- DITA - The documentation is generated in DITA 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. For DITA and DocBook documents,
this option appears as Open in Editor and the result will be
opened in Oxygen XML Editor (in the current editor).Note: To set the browser or system application that will be used, open the Preferences dialog box , 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:langattribute 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.).
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.
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 or not 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. The separator characters that are used depend upon 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 selected, local elements and attributes are included in the documentation index.
- Include resource hierarchy - Specifies whether or not the resource hierarchy for an XML Schema documentation is generated. It is deselected by default.
Export settings - Save the current settings in a settings file for further use (for example, if you need the exported settings file for generating the documentation from the command-line interface).
Import settings - Reloads the settings from the exported file.
Generate - Use this button to generate the XML Schema documentation.