Generating documentation for an XSLT Stylesheet

<oXygen/> can generate detailed documentation for the elements (top-level elements whose names are in the XSLT namespace) of an XSLT stylesheet in HTML format similar with the Javadoc documentation for the components of a Java class. You can select the XSLT elements to be included and the level of detail to be presented for each. Also the elements are hyperlinked. The user can also use its own stylesheets to obtain a custom format.

To generate documentation for an XSLT stylesheet document use the dialog XSLT Stylesheet Documentation. It is opened with the action ToolsGenerate DocumentationXSLT Stylesheet Documentation... (Ctrl+Alt+X). It can be also opened from the Project view contextual menu: Generate DocumentationXSLT Stylesheet Documentation... The dialog enables the user to configure a large set of parameters for the process of generating the documentation.

 

Figure 4.87. The Output panel of the XSLT Stylesheet Documentation dialog

The Output panel of the XSLT Stylesheet Documentation dialog

The XSL URL field of the dialog panel must contain the full path to the XSL Stylesheet file you want to generate documentation for. The stylesheet may be a local or a remote one. You can also specify the path to the stylesheet using editor variables.

You can choose to split the output into multiple files using different split criteria. For large XSLT stylesheets being documented, choosing a different split criterion may generate smaller output files providing a faster documentation browsing.

The available split criteria are:

You can export the settings of the XSLT Stylesheet Documentation dialog to an XML file by pressing the "Export settings" button. With the exported settings file you can generate the same documentation from the command line

 

Figure 4.88. The Settings panel of the XSLT Stylesheet Documentation dialog

The Settings panel of the XSLT Stylesheet Documentation dialog

When you generate documentation for an XSLT stylesheet you can choose what XSLT elements to include in the output (templates, functions, global parameters, global variables, attribute sets, character maps, keys, decimal formats, output formats, XSLT elements from referenced stylesheets) and the details to be included in the documentation:

 Generate documentation in HTML format

The generated documentation looks like the one from below:

 

Figure 4.89. XSLT stylesheet documentation example

XSLT stylesheet documentation example


The generated documentation include a table of contents. The contents can be grouped by namespace, location or component type. The XSLT elements from each group are sorted alphabetically(for templates the named templates are presented first and the match ones second). After the table of contents there is presented some information about the main stylesheet, the imported and included stylesheets. This information consists in the XSLT modules that are included or imported by the current stylesheet, the XSLT stylesheets where the current stylesheet is imported or included and the stylesheet location.

 

Figure 4.90. Information about a XSLT stylesheet

Information about a XSLT stylesheet


If you choose to split the output into multiple files, the table of contents will be displayed in the left frame. The contents will be grouped using the same criteria as the split.

After the documentation is generated you can collapse details for some stylesheet XSLT elements. This can be done using the Showing view

 

Figure 4.91. The Showing view

The Showing view


For each element included in the documentation the section presents the element type follow by the element name (the value of the name attribute or match attribute for match templates).

 

Figure 4.92. Documentation for an XSLT element

Documentation for an XSLT element