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 Sat, 29 Sep 2012 15:16:15 GMT
Publishing generated documentation to svn ? and then using svnpubsub ?

2012/9/29 Jean-Louis Boudart <jeanlouis.boudart@gmail.com>

> Any ideas ?
>
>
> 2012/9/20 Jean-Louis Boudart <jeanlouis.boudart@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" <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/
>>>
>>
>
>
> --
> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message