incubator-easyant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jean-Louis Boudart <jeanlouis.boud...@gmail.com>
Subject Plugins and buildtypes documentation
Date Tue, 04 Sep 2012 07:17:44 GMT
Hi there,

The last major step before the release is to update documentation in
particular plugin and buildtype documentation.

Before migrating to ASF, we were using an internal feature generating xml
report and then applying XSL to produce the page. The default XSL was
targeting xooki format, and the generated documentation was part of global
documentation. When building documentation, we invoked a task generating
ALL available plugins  / build types documentation.
This was taking ages and was containing lot of limitations (only last
versions were documented). We removed this piece of code as it was
containing IP issues and thoses limitations.

We now need to reimplement this.

What should be documented in plugins build types ?
 - name / version
 - short description (extracted from description in ivy file)
 - basic example of use
 - exposed targets
 - exposed extensionPoints
 - ea:parameter (properties / path)
 - nested import/include
 - dependencies

This sounds pretty easy to generate, however it may be sometime not enough
so ideally we could append manual documentation.

When should we do this ?
I suggest to do the job while releasing a plugin, to avoid generating
unnecessary documentation.

Where to publish ?
First, i thought in easyant documentation itself. But then i got another
idea.

Here are the key points that motivated me to find another solution :
If documentation is generated while releasing the plugin / buildtype, then
we would need to copy paste the generated documentation manually.
Each time a plugin is realease we would need to rebuild the whole easyant
documentation to display the updated TOC. And this needs to be done per
plugin / per version.

This could make sense for "official" apache plugins but what about
community-plugins (checkstyle ?)

Let's take a different approach.
We now have an online repository [1]. The repository is browsable through
HTTP and already provide a tree-like structure to browse plugins and each
version of them. Our online repository also provide a search feature
(finding by name for example)

Then we could consider the plugin documentation as a publication artifact :
 - generated before the release (as an HTML or a README for example)
 - published automatically to our online repository.

Our online documentation could give a link to this tree structure as an
entry point for people who wants to obtain informations on a plugin or a
buildtype.

Do you agree with this approach ?
[ ] YES
[ ] NO

[1] http://repository.easyant.org
-- 
Jean Louis Boudart
Independent consultant
Apache EasyAnt commiter http://incubator.apache.org/easyant/

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message