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 Re: Plugins and buildtypes documentation
Date Tue, 18 Sep 2012 14:33:39 GMT
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 <nicolas.lalevee@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/

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