You are viewing a plain text version of this content. The canonical link for it is here.
Posted to easyant-dev@incubator.apache.org by Jean-Louis Boudart <je...@gmail.com> on 2011/10/03 19:14:00 UTC
Plugin documentation
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/
Re: Plugin documentation
Posted by Nicolas Lalevée <ni...@hibnet.org>.
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 <je...@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/
Re: Plugin documentation
Posted by Jean-Louis Boudart <je...@gmail.com>.
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 ?
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 <je...@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/