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.
Please contact me to report errors or feature requests, questions or suggestions.
- Doron Enav for lots of bugfixes and improvements of the Javadoc comment format
- Robert Forkel for patches and the 4suite support
- the authors of Docutils
- the authors of Pyana which is a great and really simple tool to use
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.
Simply extract all files. You need the following to be installed:
- Python (tested with Python 2.4.1 on Windows XP only)
Pyana (tested with Pyana 0.9.2) or 4suite (tested with 1.01b1).
If you want to use a different XSLT processor implement and replace the
Docutils (tested with Docutils 0.3.10)
for reStructuredText (ReST) XSLT comments and package documentation files.
(If you use Javadoc style comments you might not need it, package documentation files are always expected in ReST format though.)
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
- sourcepath to XSLTs, all XSLT files under this path will be documented and
SOURCEPATH/overview.txtwill 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).
- documentation target directory. Default is
- browser window title for the documentation. Text only, no markup.
- include the contents of this ReST .txt file below the bottom navigation. Default is
- 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,
- show the contents of this ReST .txt file on the overview page. Default is
- show the information of this ReST .txt file on the help page. Default is
- 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...]
- remove all comments from given XSLTs and save results in
COMMENTSTRIPPEDPATH. Present files will be OVERWRITTEN!
- path where XSLTs will be saved after removing of all docs. Only used when option
--removedocsis given. Default directory is
- Ignored as always ON. Shows more detailed information while generarating the documentation
- show this help message and exit
- directories with XSLT files to document,e.g.
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
- single XSLT files to document, e.g.
how to document XSLT files for pyXSLdoc
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
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.
<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:
- first comment directly after
- comments directly before
The following XSLT elements are additionally documented but no comment is processed:
PyXSLdoc currently processes two different styles of comments in the XSLT files.
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.
Javadoc style comments (deprecated)
The other possibility to markup text in XSLT comments is a Javadoc style with XHTML elements (only
<i>at the moment) and additional following @-tags (currently
@see(no link generated though),
@version). If both
@paramand an XML comment before the relevant
xsl:paramelement are given the
@paramcomment 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:
- it is difficult to write as almost no IDE is validating markup in comments
- 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.
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.
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
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
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).
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
For a full ReST documented example see pyXSLdoc's own XSLT documentation.
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.
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.
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.