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 2012/09/04 07:17:44 UTC
Plugins and buildtypes documentation
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/
Re: Plugins and buildtypes documentation
Posted by Jean-Louis Boudart <je...@gmail.com>.
Publishing generated documentation to svn ? and then using svnpubsub ?
2012/9/29 Jean-Louis Boudart <je...@gmail.com>
> Any ideas ?
>
>
> 2012/9/20 Jean-Louis Boudart <je...@gmail.com>
>
>> I've added a new plugin (easyant-plugin-documentation) to generate plugin
>> documentation pages. As mentioned,generated documentation uses the same css
>> / images as our website.
>>
>> I now have issues to show you the result. I thought artifactory (the tool
>> used behind repository.easyant.org) supported browsing .html files.
>> And i was wrong. To be exact it was possible in the past but, for
>> security reasons they have changed the behavior. They provide a way to
>> browse archive content (zip for example) including .html files. This
>> feature is disabled by default and they highly encourage us to enable this
>> feature ONLY if we have strong policy to published contents. This is
>> supposed to avoid users publishing malicious stuff.
>>
>> I think it's probably time to find another solution at least for
>> publishing.
>>
>> WDYT ?
>> Le 18 sept. 2012 16:33, "Jean-Louis Boudart" <je...@gmail.com>
>> a écrit :
>>
>> I'll finish my experimentation tonight and should be able to give you a
>>> sample of generated documentation. The generated documentation import css
>>> from our website (including images;)).
>>>
>>> I agree that we can do better in future but it's better than nothing.
>>>
>>> 2012/9/10 Nicolas Lalevée <ni...@hibnet.org>
>>>
>>>>
>>>> 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
>>>>
>>>>
>>>
>>>
>>> --
>>> 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/
>
--
Jean Louis Boudart
Independent consultant
Apache EasyAnt commiter http://incubator.apache.org/easyant/
Re: Plugins and buildtypes documentation
Posted by Jean-Louis Boudart <je...@gmail.com>.
Any ideas ?
2012/9/20 Jean-Louis Boudart <je...@gmail.com>
> I've added a new plugin (easyant-plugin-documentation) to generate plugin
> documentation pages. As mentioned,generated documentation uses the same css
> / images as our website.
>
> I now have issues to show you the result. I thought artifactory (the tool
> used behind repository.easyant.org) supported browsing .html files.
> And i was wrong. To be exact it was possible in the past but, for security
> reasons they have changed the behavior. They provide a way to browse
> archive content (zip for example) including .html files. This feature is
> disabled by default and they highly encourage us to enable this feature
> ONLY if we have strong policy to published contents. This is supposed to
> avoid users publishing malicious stuff.
>
> I think it's probably time to find another solution at least for
> publishing.
>
> WDYT ?
> Le 18 sept. 2012 16:33, "Jean-Louis Boudart" <je...@gmail.com>
> a écrit :
>
> I'll finish my experimentation tonight and should be able to give you a
>> sample of generated documentation. The generated documentation import css
>> from our website (including images;)).
>>
>> I agree that we can do better in future but it's better than nothing.
>>
>> 2012/9/10 Nicolas Lalevée <ni...@hibnet.org>
>>
>>>
>>> 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
>>>
>>>
>>
>>
>> --
>> 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: Plugins and buildtypes documentation
Posted by Jean-Louis Boudart <je...@gmail.com>.
I've added a new plugin (easyant-plugin-documentation) to generate plugin
documentation pages. As mentioned,generated documentation uses the same css
/ images as our website.
I now have issues to show you the result. I thought artifactory (the tool
used behind repository.easyant.org) supported browsing .html files.
And i was wrong. To be exact it was possible in the past but, for security
reasons they have changed the behavior. They provide a way to browse
archive content (zip for example) including .html files. This feature is
disabled by default and they highly encourage us to enable this feature
ONLY if we have strong policy to published contents. This is supposed to
avoid users publishing malicious stuff.
I think it's probably time to find another solution at least for publishing.
WDYT ?
Le 18 sept. 2012 16:33, "Jean-Louis Boudart" <je...@gmail.com>
a écrit :
> I'll finish my experimentation tonight and should be able to give you a
> sample of generated documentation. The generated documentation import css
> from our website (including images;)).
>
> I agree that we can do better in future but it's better than nothing.
>
> 2012/9/10 Nicolas Lalevée <ni...@hibnet.org>
>
>>
>> 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
>>
>>
>
>
> --
> Jean Louis Boudart
> Independent consultant
> Apache EasyAnt commiter http://incubator.apache.org/easyant/
>
Re: Plugins and buildtypes documentation
Posted by Jean-Louis Boudart <je...@gmail.com>.
I'll finish my experimentation tonight and should be able to give you a
sample of generated documentation. The generated documentation import css
from our website (including images;)).
I agree that we can do better in future but it's better than nothing.
2012/9/10 Nicolas Lalevée <ni...@hibnet.org>
>
> 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
>
>
--
Jean Louis Boudart
Independent consultant
Apache EasyAnt commiter http://incubator.apache.org/easyant/
Re: Plugins and buildtypes documentation
Posted by Nicolas Lalevée <ni...@hibnet.org>.
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