From easyant-dev-return-222-apmail-incubator-easyant-dev-archive=incubator.apache.org@incubator.apache.org Wed Oct 5 20:26:37 2011 Return-Path: X-Original-To: apmail-incubator-easyant-dev-archive@minotaur.apache.org Delivered-To: apmail-incubator-easyant-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 6D6669350 for ; Wed, 5 Oct 2011 20:26:37 +0000 (UTC) Received: (qmail 78485 invoked by uid 500); 5 Oct 2011 20:26:37 -0000 Delivered-To: apmail-incubator-easyant-dev-archive@incubator.apache.org Received: (qmail 78458 invoked by uid 500); 5 Oct 2011 20:26:37 -0000 Mailing-List: contact easyant-dev-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: easyant-dev@incubator.apache.org Delivered-To: mailing list easyant-dev@incubator.apache.org Received: (qmail 78430 invoked by uid 99); 5 Oct 2011 20:26:37 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Oct 2011 20:26:37 +0000 X-ASF-Spam-Status: No, hits=1.0 required=5.0 tests=SPF_HELO_PASS,SPF_SOFTFAIL X-Spam-Check-By: apache.org Received-SPF: softfail (athena.apache.org: transitioning domain of nicolas.lalevee@hibnet.org does not designate 216.86.168.182 as permitted sender) Received: from [216.86.168.182] (HELO mxout-07.mxes.net) (216.86.168.182) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Oct 2011 20:26:29 +0000 Received: from [192.168.1.21] (unknown [86.68.205.218]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (No client certificate requested) by smtp.mxes.net (Postfix) with ESMTPSA id 4478E22E258 for ; Wed, 5 Oct 2011 16:26:07 -0400 (EDT) Content-Type: text/plain; charset=iso-8859-1 Mime-Version: 1.0 (Apple Message framework v1084) Subject: Re: Plugin documentation From: =?iso-8859-1?Q?Nicolas_Lalev=E9e?= In-Reply-To: Date: Wed, 5 Oct 2011 22:26:05 +0200 Content-Transfer-Encoding: quoted-printable Message-Id: <21A58723-3F65-402C-B335-48B5CA97AEA5@hibnet.org> References: To: easyant-dev@incubator.apache.org X-Mailer: Apple Mail (2.1084) Le 3 oct. 2011 =E0 21:33, Jean-Louis Boudart a =E9crit : > IMHO, Plugins or buildtypes should document : >=20 > - 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 > - targets and extensionPoints > - a target graph could also be useful on complex plugins >=20 > 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. >=20 > 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). >=20 > 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 >=20 > Note that EasyAnt provides a documentation plugin [1] based on = XDOC[2]. >=20 > Output format should be html based (to be browsable through easyant > website), but i would also feel happy if we support PDF. >=20 > [1] > = http://svn.apache.org/viewvc/incubator/easyant/plugins/trunk/documentation= / > [2] http://maven.apache.org/doxia/references/xdoc-format.html >=20 > 2011/10/3 Jean-Louis Boudart >=20 >> Hi there >>=20 >> 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. >>=20 >> This brings a few questions like : >>=20 >> - 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 ?) >>=20 >>=20 >> Feel free to discuss about your ideas here, we will then update the = issue >> on jira[1] with your feedbacks. >>=20 >> Any ideas are welcome. >>=20 >> [1] https://issues.apache.org/jira/browse/EASYANT-42 >>=20 >> -- >> Jean Louis Boudart >> Independent consultant >> Apache EasyAnt commiter http://incubator.apache.org/easyant/ >>=20 >=20 >=20 >=20 > --=20 > Jean Louis Boudart > Independent consultant > Apache EasyAnt commiter http://incubator.apache.org/easyant/