tomee-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Blevins (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (OPENEJB-1566) Example page generator
Date Mon, 30 May 2011 23:35:47 GMT

    [ 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

Mime
View raw message