Plugin documentation infrastructure

[dumoulin]

We're trying to design a good way for writing and publishing the documentation of a plugin.

The main goal is to have an homogeneous documentation format for all plugins, that is lightweight for the plugin author. Considered elements:

• Documentation available on the wiki
• Common format:
  • Common header with link to plugin usage documentation
  • Short description
  • API javadoc linked from the documentation
  • jar linked from the documentation
  • Detailed description
  • Requirements / Dependencies
  • Examples
• Examples could be wroten in source file and fetched from svn

Using javadoc seems to be a good solution for the developper point of view, so to have a chance to have wroten documentation :-)

Proposed design:

• Developper wrote javadoc at package level using package-info.java (available in new file wizard in NetBeans), using h3 sectioning
• Add a trac plugin that gets this documentation and integrates in the wiki adding generic information (API javadoc and jar links).

Technical hints:

• http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/overview.html
• http://docs.codehaus.org/display/GEOT/2.6+Generating+Javadoc

[dumoulin]

Instead of writing a documentation at package level, it can be more suitable to use the overview.html file, see this maven plugin documentation

[dumoulin]

OK, first solution was the best :-) Because the javadocs are aggregated, the summary of individual modules is erased, so we should put the plugin documentation at package level, see r3845

[dumoulin]

The result of this example can be see here.

[dumoulin]

I've began to code a plugin for trac, which result can be see here. What it does today:

• read the plugin description in the pom for writing the title of the page
• add links to jar and api docs

What remains: to process the javadoc html file to extract only the package description