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: Plugin documentation
Date Wed, 05 Oct 2011 20:26:05 GMT

Le 3 oct. 2011 à 21:33, Jean-Louis Boudart a écrit :

> IMHO, Plugins or buildtypes should document :
> 
>   - a few lines explaning plugin objectives and phylosophy
>   - an example of use (this can be partially generated)
>   - their dependencies (including extenal libraries, but also other
>   easyant's plugins)
>   - properties declared with <ea:parameter>
>   - targets and extensionPoints
>   - a target graph could also be useful on complex plugins
> 
> Almost all of these information can be retrieved from PluginService api in
> easyant core except the first point which needs by definition to be hand
> written.
> 
> I have no idea yet about tools that can be used to achieve this (i mean the
> hand written part, as we can generate stuff from PluginService result).
> 
> Any ideas ?
> Xooki ? A wiki syntax ? Docbook ? Using Apache Doxia (the documentation
> backend behind maven site) ?  Apache Forrest ? Others ?

I have a preference for xooki, as always :) I also have seen that every documentation done
in docbook of quite good quality. Because of docbook ? maybe, maybe not.
For our plugins, we probably should choose just one techno, but it should be pluggable right
? :)

Actually I would be fine with any choice, I will let the choice to the one who will take time
to write the documentation.

Nicolas

> 
> Note that EasyAnt provides a documentation plugin [1] based on XDOC[2].
> 
> Output format should be html based (to be browsable through easyant
> website), but i would also feel happy if we support PDF.
> 
> [1]
> http://svn.apache.org/viewvc/incubator/easyant/plugins/trunk/documentation/
> [2] http://maven.apache.org/doxia/references/xdoc-format.html
> 
> 2011/10/3 Jean-Louis Boudart <jeanlouis.boudart@gmail.com>
> 
>> Hi there
>> 
>> As you should know we've recently refactored easyant's build process to
>> make it simpler and more extandable.
>> We need to reimplement a better mechanism to generate plugin documentation.
>> 
>> This brings a few questions like :
>> 
>>   - What do you expect to find on plugin / buildtype documentation ?
>>   - Which tools / technology could we to generate this stuff ?
>>   - Which output format are we targeting ? (html ? pdf ? both ? others ?)
>> 
>> 
>> Feel free to discuss about your ideas here, we will then update the issue
>> on jira[1] with your feedbacks.
>> 
>> Any ideas are welcome.
>> 
>> [1] https://issues.apache.org/jira/browse/EASYANT-42
>> 
>> --
>> Jean Louis Boudart
>> Independent consultant
>> Apache EasyAnt commiter http://incubator.apache.org/easyant/
>> 
> 
> 
> 
> -- 
> Jean Louis Boudart
> Independent consultant
> Apache EasyAnt commiter http://incubator.apache.org/easyant/


Mime
View raw message