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 Thu, 20 Sep 2012 19:43:27 GMT
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" <jeanlouis.boudart@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 <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