Prev Up Next
Editing XML Schema schemas  /  Generating HTML documentation for an XML Schema

Generating HTML documentation for an XML Schema

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 XML Tools → Generate Documentation → Schema Documentation... . 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.

Figure 4.65. The XML Schema documentation dialog

The XML Schema documentation dialog

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:

Full model diagrams

Include in the HTML result the representation of each schema component in the <oXygen/>'s Full Model View of the schema.

Logical model diagrams

Include in the HTML result the representation of each schema component in the <oXygen/>'s Logical Model View of the schema.

Hide comments

When checked the comments are not included in the generated schema documentation.

Hide annotations

When checked the annotations are not included in the generated schema documentation.

The Options panel contain parameters for the level of details included in the documentation:

Title

The title displayed at the beginning of the HTML document and in the title bar of the web browser.

Sort by component

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."

Use JavaScript

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."

Search Included Schemas

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.

Search Imported Schemas

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.

Print all super-types

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."

Print all sub-types

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."

Print legend

If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."

Print glossary

If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."

Print NS prefixes

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:

Output folder

The path of the folder containing the HTML result and the image files.

Diagrams folder

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.

Generate chunks (Recommended for large schemas)

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.

Use hash codes for component names

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.

Generate documentation also for included and imported schemas

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.

Generate documentation only for this schema

It will not be generated HTML documentation for the XML Schemas included or imported by the schema specified in the Input panel.

Output file name

The name of the HTML file containing the documentation of the XML Schema

Links file

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]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]Note

The "xmlns" namespace attribute with the correct namespace must be provided in the mapping file for the xs3p stylesheet to work.

CSS file

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.

Open in browser

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.

[Important]Important

You can export the settings of the Schema Documentation dialog to an XML file by pressing the "Export settings" button. With the exported settings file you can generate the same HTML documentation from the command line by running the script schemaDocumentation.bat (on Windows) / schemaDocumentation.sh (on Mac OS X / Unix / Linux) located in the <oXygen/> installation folder. The script can be integrated in an external batch process launched from the command line. The command line parameter of the script is the relative path to the exported XML settings file. The files which are specified with relative paths in the exported XML settings will be made absolute relative to the directory from where the script is run.

If you want to use a modified version of the XS3P stylesheet for generating schema documentation you have to modify the XML settings file by hand and add a value to the customXS3PStylesheetURL field. You can find a copy of the xs3p.xsl stylesheet used by <oXygen/> here: ${OXYGEN_INSTALL_DIR}/frameworks/xs3p/xs3p.xsl

Example 4.9. Example of an XML configuration file for using a custom XS3P stylesheet

<serialized>
  <map>
    <entry>
      <String xml:space="preserve">xml.schema.documentation.configuration</String>
      <xmlSchemaDocumentationConfiguration>
        <field name="inputURL">
          <String xml:space="preserve">samples/personal.xsd</String>
        </field>
        <field name="outputFolder">
          <String xml:space="preserve">samples/schemaDoc</String>
        </field>
        <field name="outputFileName">
          <String xml:space="preserve">personal.xsd.html</String>
        </field>
        <field name="title">
          <String xml:space="preserve">Documentation for personal</String>
        </field>
        <field name="sortByComponent">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="useJavaScript">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="printAllSuperTypes">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="printAllSubTypes">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="printLegend">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="printGlossary">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="printNSPrefixes">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="searchIncludedSchemas">
          <Boolean xml:space="preserve">false</Boolean>
        </field>
        <field name="searchImportedSchemas">
          <Boolean xml:space="preserve">false</Boolean>
        </field>
        <field name="linksURL">
          <null></null>
        </field>
        <field name="cssURL">
          <null></null>
        </field>
        <field name="generateFullModelDiagrams">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="generateLogicalModelDiagrams">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="imagesFolder">
          <String xml:space="preserve">schemaDiagrams</String>
        </field>
        <field name="generateForImportIncludeSchemas">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="openInBrowser">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="generateChunks">
          <Boolean xml:space="preserve">false</Boolean>
        </field>
        <field name="generatePNGImages">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="useHashCodes">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="hideComments">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="hideAnnotation">
          <Boolean xml:space="preserve">true</Boolean>
        </field>
        <field name="customXS3PStylesheetURL">
          <String xml:space="preserve">frameworks/xs3p/xs3p.xsl</String>
        </field>
      </xmlSchemaDocumentationConfiguration>
    </entry>
  </map>
</serialized>



Prev Up Next
© 2008 syncRO soft ltd.