Generating documentation from a wiki with Ant and Mylyn WikiText

Cross-posted to: https://fsteeg.wordpress.com/2010/03/14/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=".">
 wikitext.tasks.classpath">
    <fileset dir="Graphviz_DOT_as_a_DSL_for_Zest">
        mylyn.wikitext.*core*.jar"/>
    </fileset>
 </path>
 <taskdef classpathref="wikitext.tasks.classpath" resource=
  "org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties"/>
 <taskdef classpathref="wikitext.tasks.classpath" resource=
  "org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties"/>
 <target name="doc">
     <!-- Set up the base wiki location to pull content from: -->
     <mediawiki-to-eclipse-help wikiBaseUrl="http://wiki.eclipse.org"
        validate="true"
        failonvalidationerror="true"
        prependImagePrefix="images"
        formatoutput="true"
        defaultAbsoluteLinkTarget="doc_external"
        dest="${basedir}"
        title="Graphviz DOT as a DSL for Zest"
        generateUnifiedToc="false">
     	<!-- 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"
                generateToc="true"/>
     </mediawiki-to-eclipse-help>
 </target>
</project>

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:

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

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

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:

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.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. [...]