pyXSLdoc

py XSLdoc - an XSL documentation tool

generate documentation for XSLT (xsldoc for XSL equals javadoc for Java)

what is it

An application to produce documentation for XSLT files in XHTML format, similar to what javadoc does for Java files. (There was at least one other app that does the same but is in no way related to pyXSLdoc, see xsldoc.org. It seems to be down for some time now though.)

pyXSLdoc can also remove all comments from a given XSLT set to optimize it for production use.

Developed because of a need of documentation for a complex set of XSLT Stylesheets of a big project and the interest to learn Python in a (hopefully) useful program.

Relying on and processing XML comments is generally not the best idea but for the purpose of this tool it seems the most natural and comfortable way. Even if the XML comments themselves should not be processed (an XML parser might just ignore them), pyXSLdoc should at least give a helpful outline for the given set of XSLT stylesheets.

kind request

Please contact me to report errors or feature requests, questions or suggestions.

thanks

download

pyXSLdoc is published under the LGPL. please find the complete details here.

pyXSLdoc v0.7 050831

For changes in this release see the README.txt.

installation

Simply extract all files. You need the following to be installed:

usage

Copy the XSLT files to document in a directory below pyXSLdoc (you could also give the complete path to your files but that would end up like that in the documentation). Alternatively copy all pyxsldoc files to the directory containing the XSLT files you want to document.
Start the documentation process with
>python xsldoc.py [options] DIRNAMES FILENAMES

options

-sSOURCEPATH, --sourcepath=SOURCEPATH
sourcepath to XSLTs, all XSLT files under this path will be documented and SOURCEPATH/doctitle.txt and SOURCEPATH/overview.txt will be used for the overview.
Alternatively you might also simply list all dirs and single XSLT files to document.
Absolute paths do not work (yet)! Please copy all files to be documented in pyxsldocs root directory or put pyxsldocs files to your XSL directory.
-j, --javadoc, --htmldocs
process comments in Javadoc style (XHTML and @tags). Default style is reStructuredText (ReST).
-dDOCPATH, --docpath=DOCPATH
documentation target directory. Default is ./_xsldoc
--windowtitle=WINDOWTITLETEXT
browser window title for the documentation. Text only, no markup.
--bottom=BOTTOM
include the contents of this ReST .txt file below the bottom navigation. Default is SOURCEPATH/bottom.txt.
--doctitle=DOCTITLE
show the contents of this ReST .txt file at the top of the overview page. Default is SOURCEPATH/doctitle.txt. If ommitted or no file is found, WINDOWTITLETEXT is used.
-oOVERVIEW, --overview=OVERVIEW
show the contents of this ReST .txt file on the overview page. Default is SOURCEPATH/overview.txt.
--helpfile=HELPFILE
show the information of this ReST .txt file on the help page. Default is ./HELP.txt.
--encoding=ENCODING
encoding of additional documenting ReST files (HELP.txt, doctitle.txt, overview.txt, directory.txt etc). Default is utf-8. (Encoding of XSLT files and comments in these is of course read from the XSLT file itself.) - [might interfere with ReST...]
-r, --removedocs
remove all comments from given XSLTs and save results in COMMENTSTRIPPEDPATH . Present files will be OVERWRITTEN!
-cCOMMENTSTRIPPEDPATH, --commentstrippedpath=COMMENTSTRIPPEDPATH
path where XSLTs will be saved after removing of all docs. Only used when option --removedocs is given. Default directory is ./_optimized.
-v, --verbose
Ignored as always ON. Shows more detailed information while generarating the documentation
-h, --help
show this help message and exit
DIRNAMES
directories with XSLT files to document,e.g. dir1 dir2
All directories and XSLT files below a given directory will be processed, so you can just use your XSLT package main directory name or use option -s.
FILENAMES
single XSLT files to document, e.g. file1.xsl path/file2.xsl

how to document XSLT files for pyXSLdoc

stylesheet documentation

comment positioning

Comments are generally expected to be directly before the corresponding element they describe. The only exception is the main comment which holds information about the whole stylesheet. This comment is (due to XML parser problems) the first comment after the opening xsl:stylesheet or xsl:transform element.

This exception might lead to a problem if there is a commentable element directly after the xsl:stylesheet's comment without its own comment (the stylesheet's comment would be used twice then). In that case simple add an empty comment after the stylesheets comment.

Example: 

<xsl:stylesheet>
<!-- stylesheet comment -->
<!--
comment for the following xsl:param element
do not leave out as xsl:param would use the
same comment as xsl:stylesheet
in doubt simply add empty comment here
-->
 <xsl:param/>
<!-- comment for the following xsl:template element -->
<xsl:template/> [...]

Comments for the following XSLT elements are processed and used in the documentation:

The following XSLT elements are additionally documented but no comment is processed: xsl:import, xsl:include, xsl:output, xsl:namespace-alias, xsl:preserve-space and xsl:strip-space.

comment format

PyXSLdoc currently processes two different styles of comments in the XSLT files.

  1. reStructuredText style comments (prefered)

    Since pyXSLdoc v0.4 the default comment format is reStructuredText (ReST).
    Following a simple example:

    a paragraph with some *emphasized*, **strong** or ``tt`` text.

	a blockquote which is simply indented (so if you
	want normal paragraphs, start in the first column)

- a list
	* with a sublist
		1. or an ordered sublist
- second item in the outer list

since
	a definition list might be useful for meta data
	like author or version information

    You can use almost all possibilities the docutils format offers like headlines, paragraphs, lists (ordered, unordered, definition lists, field lists etc.), blockquotes, text markup (emphasized, strong etc.) and lots more. See the Docutils documentation for details of how to write structured comments in ReST format.

    There are only a few minor limitation using ReST in XML.
    XML comments are not allowed to contain two or more "-" characters directly after another. ReST uses these to markup some elements but there is almost always a replacement character. Therefore use other characters like "=" or "~" to markup headlines or to build XHTML hr elements. For tables in ReST no substitution character is currently available but the need to use tables in comments should be quite rare (and not even the Javadoc style comments handle these).
    These limitations of course apply only for ReST in XML comments and not for the ReST package documentation files.

  2. Javadoc style comments (deprecated)

    The other possibility to markup text in XSLT comments is a Javadoc style with XHTML elements (only <p>, <ol>, <ul>, <li>, <br>, <b> and <i> at the moment) and additional following @-tags (currently @author, @deprecated, @param, @see (no link generated though), @since, @version). If both @param and an XML comment before the relevant xsl:param element are given the @param comment is used.
    Following a short example: 

    <p>a paragraph with some <em>emphasized</em> or
<strong>strong</strong> text.</p>
<ul>
  <li>a list
    <ul>
      <li>with a sublist
        <ol>
          <li>or an ordered sublist</li>
        </ol>
      </li>
    </ul>
  </li>
  <li>second item in the outer list</li>
</ul>
@since v0.1

    There are some IMHO severe problems using XHTML in XML comments though:

    1. it is difficult to write as almost no IDE is validating markup in comments
    2. a high possibility of producing invalid documentation which is generated in XHTML/XML format and the markup in the comments is not checked or changed by pyXSLdoc

    Also additional package documentation files will always be processed as ReST files.

    So it is best to avoid Javadoc style comments, but do if you want to or have to (if you have lots of Javadoc commented XSLT files already).

Generally I think an almost naturally written text format like reStructuredText is much easier to write and read and so it is more likely that a proper documentation is done at all as it also helps to understand the stylesheet while working in the code.

package documentation

Additionally to process each stylesheet's comments a package documentation is generated which also may be supplied with some additional commenting files. These are always expected to be in ReST format.

doctitle.txt

In the first given directory to document (or the one given with option --sourcepath) pyXSLdoc looks for a ReST formatted "doctitle.txt" file. The contents of this file is displayed at the top of the overview page. You can provide your own file with option --doctitle.

overview.txt

In the first given directory to document (or the one given with option --sourcepath) pyXSLdoc looks for a ReST formatted "overview.txt" file (which directly corresponds to Javadocs "overview.html" file). The contents of this file will be shown on the overview page of the documentation below the list of contained directories. You may overwrite this behaviour and provide a custom file via option -o.

directory.txt

For every directory pyXSLdoc looks for a ReST formatted "directory.txt" file. The contents will be shown on the directory tab of the documentation (therefore corresponds to the Javadoc "package.html" file).

help.txt

Per default the contents of the ReST formatted "HELP.txt" file is shown on the help page. Again you may provide your own file with option --helpfile.

examples

For a full ReST documented example see pyXSLdoc's own XSLT documentation.

Generated with
python xsldoc.py -spyxsldoc -d__doc__ --windowtitle=pyXSLdoc --doctitle=VERSION.txt -oREADME.txt
or (full options)
python xsldoc.py --sourcepath=pyxsldoc --docpath=__doc__ --windowtitle=pyXSLdoc --doctitle=VERSION.txt --overview=README.txt --helpfile=HELP.txt

For an example with the default ReST assumed comment processing see the ReST documentation for a ReST commented XSLT file.
Generated with
python xsldoc.py -sexamples -dexamples/rest --windowtitle="pyXSLdoc ReST style example" --doctitle=examples/rest.txt

The same example processed with option -j (javadoc or htmldocs) of a Javadoc commented XSLT. See the generated Javadoc documentation for a Javadoc commented XSLT file.
Generated with
python xsldoc.py -sexamples --htmldocs -dexamples/javadoc --windowtitle="pyXSLdoc Javadoc style example" --doctitle=examples/javadoc.txt

The comment style not expected in each example (e.g. the ReST stylesheet in the second example) leads to the seen errors, which do not occur if you stick to one style of course.