Documenting XWiki Velocity Macros

A new tool is available to document XWiki velocity macros. The tools is a modified version of velocidoc. This tool can run from the command-line and analyse file-system templates, an export of a Wiki or a Wiki using an XML-RPC remote connection. It can also analyse a Wiki from within itself.

The source code is available at http://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/velocidoc/

Here is the documentation of the templates directory of XWiki Platform Web 1.6 trunk

How to install and run from the Command-Line

• Download velocidoc-bin-0.3.zip from this page
• Extract the zip file
• Run velocidoc.sh for the help (you'll need to create a bat file for Windows)

The following command-line parameters are available:

• -src: Source to use. It can be a directory where file system based templates or export XWiki XML files are present. It can also be the URL of the XML-RPC connection of a Wiki.
• -dst: Destination of the documentation. It can be a directory or a zip file (use -z in addition)
• -z: The Destination directory is a zip file
• -user: Wiki User name for the XML-RPC connection
• -pass: Wiki password for the XML-RPC connection
• -name: Base package name to use
• -pkg: Comma separated list of spaces to restrict analysis to

How to install and run from within XWiki

• Download xwiki-plugin-velocidoc-0.3.jar and xwiki-core-xmlrpc-client-1.5.jar from this page
• Install them in your WEB-INF/lib installation and restart your XWiki
• Import velocidoc-0.3.xar in your Wiki
• Visit XWiki.Velocidoc. You can choose 3 parameters to generate your documentation:
  • Name: name of your wiki: Test
  • Filename: name of your output zip file: test.zip
  • Spaces: list of spaces to analyse: leave empty if your wiki is small
• The output will be a zip file attached in XWiki.Velocidoc and a macro will automatically display it in the page