pyxsldoc - xsldoc documentation for XSLT stylesheets similar to javadoc ============================================================================ Copyright © 2004-2005 Christof Höke Published under the LGPL, see http://cthedot.de/pyxsldoc/license.html You need at least Python 2.2, `Docutils `__ if you use the (default) reStructuredText comment format and a XSLT processor, currently supported are `Pyana `__ and `4suite `__. Tested with Python 2.4.1 on Windows XP with Pyana 0.9.2, 4suite 1.01b1 and Docutils 0.3.10 installed. Please visit http://cthedot.de/pyxsldoc/ for full details and updates. See also the README.txt and documentation. Use option ``-h`` for command line options. directory structure ------------------- ``xsldoc.py`` pyxsldoc start script ``./__doc__`` pyxsldoc's own xsldocs ``./_xsldoc`` default target for the resulting documentation (overwrite with option -d) ``./_optimized`` default target of XSLs after running pyxsldoc with option --removedocs ``./pyxsldoc`` the pyxsldoc package ``./pyxsldoc/xsl`` the pyxsldoc XSLT files used for the documentation process todo ==== * resolve --encoding of ReST files? ReST does have problems with the unicode encoding bytes of a file...? * add short ReST documentation * xsl:import and xsl:include docs? * iso-8859-15 XSLTs do not work??? (Pyana?) * Namespace for pyxsldoc XML? * add support for absolute paths? * add more cmdline options of the standard javadoc? - header? (right of top nav) header.txt? - footer? (right of bottom nav or copyright before bottom nav?) footer.txt? **THESE OPTIONS DO NOT WORK YET!** changes ======= 0.7 050831 - bugfix in comment.py, thanks to Robert Forkel - transformer now optionally uses Pyana or 4suite, the 4suite support thanks to Robert Forkel again - minor "cosmetic" changes in CSS and XHTML output 0.69.1 050713 checked code and removed unused imports from main script 0.69 050712 * bugfix in util.py return value if no comment was given was wrong * bugfix in xsl/doc.xsl param anchor links did not work * cmdline option -v --verbose is ignored and always set to True now 040804 * tested with docutils 0.3.5, no release 0.68 040717 * clean up of stylesheet documentation. * template summary shows only distinguishing attributes (name, match, mode and priority) and not all params anymore * template detail view reduced as well and slight font style adjustments * CSS adjusted for hopefully easier reading 0.67 040712 * new option --bottom shows the text of this given ReST file below the bottom navigation (useful e.g. for copyright information) 0.66 040709 * BUGFIX: params of match templates were not processed until now (detected and fixed by Doron Enav) * BUGFIX: template with match *and* name attribute did ommit the match part * BUGFIX: IndexError if not doctitle was given... * priority of xsl:template is processed now * slight changes to detail view of templates * added more testcases to XSL files in /examples 0.65 040707 * fixed a bug that both the Javadoc @param comment and the comment before the xsl:param elements are shown in the documentation. @param has precedence before the xsl:param comment in -j mode now. (suggestion by Doron Enav) * no "default value" is printed if none is given (suggestion by Doron Enav) 0.64 040701 * for ReST version: overview, directory pages and stylesheets pages show short comments for directories, stylesheets and XSLT elements. For these short comments the first paragraph of each comment is used, none if any other element like a header, list or blockquote is the first elements * new option --encoding to specify the encoding of additional ReST documentation files like help.txt overview.txt or directory.txt. (Encoding of XSLT files and comments in these is of course read from the XSLT file itself) * --verbose output prints messages about used doctitle, overview and helpfile ReST files * slight changes to documentation output 0.63 040627 * comments will be strip()ped before converted from ReST to XHTML to be able to use inline comments like , until now this always gave a
which should occur with intent only very rarely * --windowtitle will be shown as Main Headline on overview page if no doctitle given or found * new option --doctitle, doctitle.txt in ReST format will be shown at the top of overview page * bugfixes and fixed typo in help 0.62 040626 * enhanced tree view * enhanced documentation for named templates, parameters will be documented now * index: corrected link to named template parameters * presentation adjustments in CSS stylesheet * bugfixes 0.61 040625 * BUGFIX: remove comments (-r) did not work in 0.60... * new option --helpfile=HELP.txt to specify content for help page * new HELP.txt about pyXSLdoc's documentation, shown on the help tab if not overwritten with open --helpfile * removed "deprecated" from navigation as it is not generated anyway * simplified code 0.60 040622 * new option -v, --verbose: show status of documentation process in stdout * bugfixes and refactoring * used Pyana.URI in transformer, resolves also the strange xsl:import href which had to be used before * re-added links to imported/included XSLTs. links are assumed to be relative, otherwise the doc internal links will not work. * resolved internal unicode handling, only transformer.py (Pyana) and comment.py (minidom) handle with str objects 0.60b 040618 * id and class attributes are filtered out of ReST XHTML to not interfere with pyXSLdocs own CSS classes * added detailed documentation how to comment a XSL package to website 0.54 not released * internal changes: - transformer.py cleanup and commented 0.53 not released * new option - --windowtitle: browser window title for the documenation (only text, no tags possible) * moved docutils import in util.py to function that needs it so if you use javadoc style comments only pyXSLdoc still works without having to install docutils. * internal changes: - deleted unnessessary import of docutils in comment.py - init param changes (some more, some optional) - xsldoc version and date info in resulting HTML as comments - removed index.js file as it is not used anyway 0.52 040601 documentation of xsl:namespace-alias shows prefixes with connected URIs now. (thanks to Jarno Elovirta!) 0.51 040531 - links to xsl:import and xsl:include stylesheets may not be right as different XSLT processors handle relative URLs in different ways (Pyana e.g. uses the path relative to the calling application, so in pyxsldoc this is relative to the main xsldoc.py.) - pyXSLdoc assumes paths relative to the importing or including stylesheet as there would be no better way (if you know one, drop me a line, thanks!). so the links on the stylesheet page may be wrong. for the moment these are completely disabled. 0.50 040530 - all directories containing XSLT files below given sourcedirs (with options -s or in the given list) will be processed now - new options "-s" and "-o": from given "--sourcepath=SOURCEPATH" or the first given directory a file "overview.txt" will be used on the overview summary. overwriting of this default behaviour possible with option "--overview" - for each directory a "directory.txt" file in ReST format will if present be used for the directory page overview - new option "-c" - uses optparse module for option parsing now 0.43 040524 more xsl elements are documented, added - xsl:attribute-set - xsl:decimal-format - xsl:key - xsl:namespace-alias (TODO: maybe show URIs?) - xsl:preserve-space so all top level XSLT elements are documented now javadoc style doc has same font-family a ReST docs now 0.42 040523 - xsl:strip-space is documented now - xsl:params have summary and detail section now - documentation layout and CSS style tweaked - fonts, margins and colors changed 0.41 040523 - new directory structure - new "--removedocs" option, filters all documentation comments out of given XSLT files (suggestion by Peter Siebler) 0.4 not released 0.35 040522 bugfix release bugfix in template summary table contributed by *Doron Enav* (again) 0.4b - USAGE CHANGE "-d doctargetdir" replaces "-b basedir"! - COMMENT CHANGE the default style of the XSLT comments is reStructuredText specify option "--htmldocs" to process the former Javadoc (HTML and @tags) style - added this README.txt 0.4a - made package of pyxsldoc to clean the docdir and added xsldoc.py start file so usage stays the same - moved pyxsldoc own xsldoc to pyxsldocxsldoc - removed all "from" imports 0.34 040515 processing of HTML comments and small changes - br, b, i, ol, ul, p and   elements in XSL comments are processed, thanks to *Doron Enav* for the XSL templates - default value of xsl:param element is shown, might not - work for nested values though - slight improvement of inline comments - xsl:output values displayed in code font 0.33 030722 finalized unicode enhancement - non-ASCII characters in XML comments allowed now - need to set sys.setdefaultencoding removed - problem with "-b" basedir option fixed (generated an empty doc dir) 0.32 030225 bugfix and small extension release: - "mode" of templates is shown in xsldoc - bug in python code fixed (a var was not defined...) - dependency on PyXML class removed (not really tested yet) 0.31 030217 mainly bugfix release: - doc of the whole stylesheet is now processed. this comment has to be AFTER the root-element as expat chokes on comments before the root-element (i thought it is possible though) - cssstyles changed for IE 6 strange frame behaviour - deleted a ref to PyXML, this package is normally not needed, really should not be needed now - pyxsldoc's own xsl documentation now in folder xsldocdoc 0.3 030120 first release - comments are processed now - single file processing did not work as expected - various css and xsl improvements 0.25 030118 readme added and windows exe build - not included anymore 0.24 030112 changed output (sorting of stylesheets, styling, etc) 0.23 030108 directory-summaries and single stylesheet files added 0.22 030107 changes to xsl/css navigation and sorting of output 0.21 030105 bugfixin and split into more and easier modules/classes 0.2 030103 complete rewrite in oop style 0.1 021228 testversion if this works at all, quite complete but very messy