From easyant-dev-return-312-apmail-incubator-easyant-dev-archive=incubator.apache.org@incubator.apache.org Tue Sep 4 07:18:17 2012 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 4ACF2DC94 for ; Tue, 4 Sep 2012 07:18:17 +0000 (UTC) Received: (qmail 66297 invoked by uid 500); 4 Sep 2012 07:18:17 -0000 Delivered-To: apmail-incubator-easyant-dev-archive@incubator.apache.org Received: (qmail 66142 invoked by uid 500); 4 Sep 2012 07:18:14 -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 66050 invoked by uid 99); 4 Sep 2012 07:18:12 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Sep 2012 07:18:12 +0000 X-ASF-Spam-Status: No, hits=1.5 required=5.0 tests=HTML_MESSAGE,RCVD_IN_DNSWL_LOW,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (nike.apache.org: domain of jeanlouis.boudart@gmail.com designates 209.85.210.175 as permitted sender) Received: from [209.85.210.175] (HELO mail-iy0-f175.google.com) (209.85.210.175) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Sep 2012 07:18:05 +0000 Received: by iaky10 with SMTP id y10so8901515iak.6 for ; Tue, 04 Sep 2012 00:17:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:date:message-id:subject:from:to:content-type; bh=EhgQ9qsR0UxBNJ8U4tAPVPJQzwuSrZr/YgRtzWoGkUU=; b=tI1Qm7dJlSAPvv3TpEMHmgGHU25PFCDkkMoF+ONRKTaFVWKpfLqj9yblBENcPaW8tb CgtBkN2I3INiCJk8au7jsHr+qsYdouJNH863QgXNEpWZYro+9BHYYR6pm+Fuc7cMmB3l ebF48z1tcxja0kCCQI8dNkdQVyqGsgSWpjNLo9wmXhkMipHZAsHOh/rYTZs9tkuWvb3X 0aEkKxFdTQjyEJRZ48sB5idJ6rX/vz1Huz+9cPSFNTOXAiKiRDC2xrW0yX7aAcEjbcQX 78Jto4BnlNOLTjJFmoAe1PpYDMJ3SrIy5mhp3TJXt5ONy1O6R5My8i9Zi66+sg3ltfG6 lGMA== MIME-Version: 1.0 Received: by 10.50.186.169 with SMTP id fl9mr1270645igc.9.1346743065080; Tue, 04 Sep 2012 00:17:45 -0700 (PDT) Received: by 10.43.49.5 with HTTP; Tue, 4 Sep 2012 00:17:44 -0700 (PDT) Date: Tue, 4 Sep 2012 09:17:44 +0200 Message-ID: Subject: Plugins and buildtypes documentation From: Jean-Louis Boudart To: easyant-dev@incubator.apache.org Content-Type: multipart/alternative; boundary=14dae9340b81ff741f04c8db0d0e --14dae9340b81ff741f04c8db0d0e Content-Type: text/plain; charset=ISO-8859-1 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/ --14dae9340b81ff741f04c8db0d0e--