To generate HTML documentation for a XML Schema document similar with the Javadoc documentation for Java classes use the dialog Schema documentation. It is opened with the action → → (Ctrl+Alt+S). It can be also opened from the Project Tree contextual menu: The dialog enables the user to configure a large set of parameters of the process of generating the HTML documentation. →
The HTML documentation contains images corresponding to the schema definitions as the ones displayed by the schema diagram view. 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. Also 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 preserved in the generated HTML documentation.
The text field of the Input panel must contain the full path to the XML Schema (XSD) file, if the schema is composed of only one file, or the full path to the main XSD file of the XML Schema document, that is the file that includes or imports other modules of the document.
<oXygen/> is able to include images of the XML Schema components in the final HTML result. The supported image formats are PNG and JPG. 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 parameters related to images are:
Include in the HTML result the representation of each schema component in the <oXygen/>'s Full Model View of the schema.
Include in the HTML result the representation of each schema component in the <oXygen/>'s Logical Model View of the schema.
When checked the comments are not included in the generated schema documentation.
When checked the annotations are not included in the generated schema documentation.
One of the PNG or JPG formats.
The Options panel contain parameters for the level of details included in the documentation:
The title displayed at the beginning of the HTML document and in the title bar of the web browser.
If this parameter is set to "true", the schema components are presented sorted by type and name. Otherwise, they are presented in the order that they appear in the schema. By default, this parameter is set to "true."
The generated XHTML document uses JavaScript to hide some details like the underlying schema component XML representation, which can be made to appear with a button press. Since some people have ideological objections to JavaScript, this feature can be turned off. If this parameter is set to "true", JavaScript will be used in the generated documentation. Otherwise, it won't. By default, this parameter is set to "true."
If this parameter is set to "true", xs3p will search for components in "included" schemas when creating links and generating the XML Instance Representation table. When this parameter is set to "true", the "linksFile" parameter must also be set, which is described below. Otherwise, an error will be raised. This search is recursive, so schemas "included" in the current schema's "included" schemas will also be searched.
If this parameter is set to "true", xs3p will search for components in "imported" schemas when creating links and generating the XML Instance Representation table. The above discussion for the "searchIncludedSchemas" parameter also applies to this parameter. Also, when this parameter is set to "true", the "linksFile" parameter must also be set.
The type hierarchy of a global type definition is displayed in its section. If this parameter is set to "true", all super-types of the current type are shown in the type hierarchy. Otherwise, only the immediate parent type is displayed. By default, this parameter is set to "true."
This parameter has a similar concept as printAllSuperTypes. If it is set to "true", all sub-types of the current type are shown in the type hierarchy. Otherwise, only the direct sub-types are displayed. By default, this parameter is set to "true."
If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."
The Output panel contains parameters for the output folder and output file:
The path of the folder containing the HTML result and the image files.
The folder where the images are going to be saved relative to the output file. If there is no folder specified, the images will be saved in the same directory as the output file.
If it is true the HTML result is organized as a main file containing only a table of contents with links to other HTML documents containing descriptions of the schema components. If it is false all the documentation will be stored in one HTML file.
If enabled then the anchors and links will be generated using the hashcode of the component identifier instead of using the identifier itself. This is useful when the schema component names contain characters that are not directly supported by the browsers or by the file system.
It will be generated HTML documentation also for the XML Schemas included or imported by the schema specified in the Input panel. The documentation can be navigated from a schema to the included/imported ones and back to the first schema following HTML hyperlinks.
It will not be generated HTML documentation for the XML Schemas included or imported by the schema specified in the Input panel.
The name of the HTML file containing the documentation of the XML Schema
the file which maps from file locations of "included" and "imported" schemas to the file locations of their xs3p-generated documentation. This file must be provided if either "searchIncludedSchemas" or "searchImportedSchemas" is set to true. If relative addresses are used to specify the location of external xs3p-generated documentation, they must be relative to documentation file currently generated.
![]() | Note |
---|---|
The external documentation files does not need to exist at the time of generating the documentation for the current schema. The mapping is specified in XML. The dtd and schema for this mapping syntax are "links.dtd" and "links.xsd" respectively. |
![]() | Note |
---|---|
The "xmlns" namespace attribute with the correct namespace must be provided in the mapping file for the xs3p stylesheet to work. |
The path to a CSS file which will be referred from the result HTML. This is useful for specifying a custom CSS stylesheet to be used in the generated HTML documentation instead of the default one.
If it is true the HTML result will be opened with the default Internet browser set in Preferences or with the system application for HTML files.