incubator-easyant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicolas Lalevée <nicolas.lale...@hibnet.org>
Subject Re: Plugins and buildtypes documentation
Date Mon, 10 Sep 2012 08:20:44 GMT

Le 4 sept. 2012 à 09:17, Jean-Louis Boudart a écrit :

> 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 ?

I like the simplicity, but it would only work for browsable http repository, and where the
documentation can fit in one html page (no images, no shared css).

So I don't see it as a long term solution. But for now, I can live with it. I can also live
without any documentation too :)

Nicolas


Mime
View raw message