Altova XMLSpy 2024 Enterprise Edition

The Schema Design | Generate Documentation command generates detailed documentation of the active schema: XML Schema or JSON schema. This section describes the generation of XML Schema documentation. The procedure for generating JSON schema documentation is similar. For details about generating JSON schema documentation and a description of documentation generation settings, see the section Generating JSON Schema Documentation.

 

Generating XML Schema documentation

If an XML Schema document is active and you click the Generate Documentation command, the Schema Documentation dialog (screenshot below) is displayed. In this dialog, you can select options for the documentation.

 

In the Documentation Design pane of the dialog you can select whether to use the fixed XMLSpy design for the generated documentation or whether to use a customized design created in a StyleVision SPS. Select the option you want. Note that PDF output is available only for documentation generated with a StyleVision SPS, not for documentation generated using a fixed design. How to work with a user-defined design is described in the section, User-Defined Design.

Click to expand/collapse

Click to expand/collapse

The other options in the Schema Documentation dialog are explained below:

 

The required format is specified in the Output Format pane: either HTML, Microsoft Word, RTF, or PDF. (The PDF output format is only available if you use a StyleVision SPS to generate the documentation.) On clicking OK, you will be prompted for the name of the output file and the location to which it should be saved.

Microsoft Word documents are created with the .doc file extension when generated using a fixed design, and with a .docx file extension when generated using a StyleVision SPS.

The PNG format for images is available in all output formats. The SVG image format is available in HTML and PDF output formats.

The documentation can be generated either as a single file or be split into multiple files. When multiple files are generated, each file corresponds to a component. What components are included in the output is specified using the check boxes in the Include pane. In fixed designs, links between multiple documents are created automatically.

For HTML output, the CSS style definitions can be either saved in a separate CSS file or embedded in the HTML file (in the <head> element). If a separate CSS file is created, it will be given the same name as the HTML file, but will have a .css extension. Check or uncheck the Embed CSS in HTML check box to set the required option.

The Embed Diagrams option is enabled for the MS Word, RTF, and PDF output options. When this option is checked, diagrams are embedded in the result file, in PNG or SVG format. Otherwise diagrams are created as image files (PNG or SVG), which are displayed in the result file via object links.

When the output is HTML, all diagrams are created as document-external PNG files. If the Create folder for diagrams check box is checked, then a folder will be created in the same folder as the HTML file, and the PNG files will be saved inside it. This folder will have a name of the format HTMLFilename_diagrams. If the Create folder for diagrams check box is unchecked, the image files will be saved in the same folder as the HTML file.

Links to local files (such as diagram image files and external CSS file) can be relative or absolute. In the Generate links to local files pane, select the appropriate radio button according to the option you prefer.

In the Include pane, you select which item types you want to include in the documentation. Each item of the selected types will be displayed in the generated documentation. For example, if Local Attributes is checked, then the description of each local attribute is displayed as a separate entry. The Index option lists all related schemas at the top of the file, with their global components organized by component type. The Check All and Uncheck All buttons enable you to quickly select or deselect all the options in the pane. Note that the Include option does not affect the display of an item type within the graphical definitions. That display is controlled by the settings you make in the Schema Display Configuration dialog. So if you wish to disable the display of attributes within the graphical representation of a schema item, then uncheck the Attributes option in the Schema Display Configuration dialog.

The Details pane lists the details that may be included for each component. Select the details you wish to include in the documentation. The Check All and Uncheck All buttons enable you to quickly select or deselect all the options in the pane.

The Show Result File option is enabled for all output options. When this option is checked, the result files are displayed in Browser View (HTML output), MS Word (MS Word output), and the default applications for .rtf files (RTF output) and .pdf files (PDF output).

 

Parameter values

If the StyleVision SPS contains one or more parameter definitions, then on clicking OK, a dialog pops up listing all the parameters defined in the SPS. You can enter parameter values in this dialog to override the default parameter values that were assigned in the SPS.

 

© 2017-2023 Altova GmbH