Generating documentation from a wiki with Ant and Mylyn WikiText

I was planning to update the dot4zest documentation when I saw the recent posts by David Green and Chris Aniszczyk on generating Eclipse help right from the wiki.

Outdated and duplicated documentation is one of the topics I keep encountering in basically every project I work on. Given that I was already generating the dot4zest help with WikiText (but from a file, not straight from the wiki) I decided to give it a try.

Following the instructions in the crowdsourcing example, I first got the WikiText standalone Jars and set up a small Ant script:

<project name="dot4zest" default="doc" basedir=".">
    <fileset dir="Graphviz_DOT_as_a_DSL_for_Zest">
 <taskdef classpathref="wikitext.tasks.classpath" resource=
 <taskdef classpathref="wikitext.tasks.classpath" resource=
 <target name="doc">
     <!-- Set up the base wiki location to pull content from: -->
     <mediawiki-to-eclipse-help wikiBaseUrl=""
        title="Graphviz DOT as a DSL for Zest"
     	<!-- Set up which wiki page to pull from: -->
        <path name="Graphviz_DOT_as_a_DSL_for_Zest"
                title="Graphviz DOT as a DSL for Zest"

Running the Ant file (ant in a console or double-click after dragging it onto the Ant view in Eclipse) pulls the content from the wiki location specified in the script and generates the Eclipse help:

Generated Eclipse Help TOC

Next, I updated the help TOC extension in the plugin.xml:

<extension point="">
      <toc file="Graphviz-DOT-as-a-DSL-for-Zest-toc.xml" primary="true"/>

Then I added the generated help resources to the binary build in the build tab of the manifest editor to have them included in the deployed bundle:

Including the generated help resources in the binary build

With this, the wiki page content is included in the Eclipse online help of the bundle (Help > Help Contents).

Being based on Mylyn WikiText – which supports many wiki markup formats (textile, confluence, mediawiki, trac and twiki) as well as output to other formats than Eclipse help (e.g. DocBook and DITA) – I imagine this approach could be used in many project documentation setups.

I really like this WikiText feature both for technical and collaborative reasons: it reduces duplication (DRY for docs!) and eases collaboration on documentation. Instead of being part of the code repository, the help content is made available to a wider range of editors than the people committing code – which I believe is useful for projects of any size.


About this entry