From commits-return-13281-apmail-openejb-commits-archive=openejb.apache.org@openejb.apache.org Mon May 30 23:36:30 2011 Return-Path: X-Original-To: apmail-openejb-commits-archive@www.apache.org Delivered-To: apmail-openejb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 8A19061F8 for ; Mon, 30 May 2011 23:36:30 +0000 (UTC) Received: (qmail 89315 invoked by uid 500); 30 May 2011 23:36:30 -0000 Delivered-To: apmail-openejb-commits-archive@openejb.apache.org Received: (qmail 89289 invoked by uid 500); 30 May 2011 23:36:30 -0000 Mailing-List: contact commits-help@openejb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@openejb.apache.org Delivered-To: mailing list commits@openejb.apache.org Received: (qmail 89280 invoked by uid 99); 30 May 2011 23:36:30 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 30 May 2011 23:36:30 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.116] (HELO hel.zones.apache.org) (140.211.11.116) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 30 May 2011 23:36:28 +0000 Received: from hel.zones.apache.org (hel.zones.apache.org [140.211.11.116]) by hel.zones.apache.org (Postfix) with ESMTP id 57510EA9C6 for ; Mon, 30 May 2011 23:35:47 +0000 (UTC) Date: Mon, 30 May 2011 23:35:47 +0000 (UTC) From: "David Blevins (JIRA)" To: commits@openejb.apache.org Message-ID: <1026677370.54578.1306798547354.JavaMail.tomcat@hel.zones.apache.org> In-Reply-To: <1061358025.54558.1306798067368.JavaMail.tomcat@hel.zones.apache.org> Subject: [jira] [Commented] (OPENEJB-1566) Example page generator MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit X-JIRA-FingerPrint: 30527f35849b9dde25b450d4833f0394 X-Virus-Checked: Checked by ClamAV on apache.org [ https://issues.apache.org/jira/browse/OPENEJB-1566?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13041333#comment-13041333 ] David Blevins commented on OPENEJB-1566: ---------------------------------------- Most the examples do not have any documentation. There are some wiki pages for some of the examples, but these are hard to create and maintain. The examples change frequently enough that we really should have documentation that goes with each version of the examples. If we put a README.md file in each example and use Markdown which is a really simple text format that has many tools capable of generating html, we could probably generate a web page for each example. Then we could generate a index for all the examples. We could then take this all and upload it to the website Small proof of concept: - http://svn.apache.org/repos/asf/openejb/trunk/openejb3/examples/simple-stateless/README.md - http://people.apache.org/~dblevins/simple-stateless.html Something kind of like this, but nicer looking, with breadcrumbs and links for navigating around to other examples. Side benefit is that README.md files are also handled by github. Load up this page and hit refresh twice: - https://github.com/apache/openejb/tree/trunk/openejb3/examples/simple-stateless IDEAS FOR AFTER SOMETHING IS WORKING Perhaps at some point some xref style processing of the source and links to the source Perhaps at some point use ASM to see what annotations and API classes were used and make an index that lists examples by which APIs are used Perhaps at some point use Swizzle stream to do a sort of SNIPPET thing like the Confluence plugin, so we wouldn't have to copy source into the example > Example page generator > ---------------------- > > Key: OPENEJB-1566 > URL: https://issues.apache.org/jira/browse/OPENEJB-1566 > Project: OpenEJB > Issue Type: Improvement > Components: documentation, examples, website > Reporter: David Blevins > Priority: Critical > Labels: documentation, examples, markdown, website > -- This message is automatically generated by JIRA. For more information on JIRA, see: http://www.atlassian.com/software/jira