I'm going to resurrect this thread, see if we can come to a consensus on what we want to use for documentation.
As I currently understand things there are a few options on the table for documentation of DeltaSpike: * Apache CMS -- AIUI, this is a perl script that runs some extra stuff. More info and history is available at http://www.apache.org/dev/cms. Not sure if you have to be using SVN to get the rebuild on checkin support or not. * DocBook -- I think we're all familiar with DocBook. * Sphinx or plain ReStructuredText -- A wiki markup. Somewhat difficult to use and remember, heavily used in the Python community * Markdown -- We all know what that is. It has native support in apache-cms. Great for simple stuff, starts breaking down quickly when used for technical documentation * asciidoc -- Another wiki markup.http://www.methods.co.nz/asciidoc/. Easy to use, very similar to markdown, more expressive, very similar feature set to docbook. Earlier in this thread we wanted to have the ability to have buildable docs by maven. However, if there isn't a plugin already available, which to my knowledge would take out everything but docbook and sphinx, possibly markdown, we'd have to build one. We also want it easy for contributors to use, which is a downside to docbook and sphinx. If anyone has any others they'd like to put into the match, please speak up. On Fri, Apr 13, 2012 at 5:57 PM, Gerhard Petracek (Updated) (JIRA) < [email protected]> wrote: > > [ > https://issues.apache.org/jira/browse/DELTASPIKE-13?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel] > > Gerhard Petracek updated DELTASPIKE-13: > --------------------------------------- > > Fix Version/s: 0.4-incubating > > > Choose documentation format and tools > > ------------------------------------- > > > > Key: DELTASPIKE-13 > > URL: https://issues.apache.org/jira/browse/DELTASPIKE-13 > > Project: DeltaSpike > > Issue Type: Task > > Reporter: Shane Bryzak > > Assignee: Jason Porter > > Fix For: 0.4-incubating > > > > > > We need to decide on a documentation format for the DeltaSpike > documentation. Requirements are: > > 1. Kept in the VCS with the DeltaSpike codebase > > 2. Buildable with Maven > > 3. Can generate multiple formats, including HTML and PDF > > Currently the "industry standard" is DocBook, however there may be other > alternatives which are more suitable. Suggestions welcome here. > > -- > This message is automatically generated by JIRA. > If you think it was sent incorrectly, please contact your JIRA > administrators: > https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa > For more information on JIRA, see: http://www.atlassian.com/software/jira > > > -- Jason Porter http://lightguard-jp.blogspot.com http://twitter.com/lightguardjp Software Engineer Open Source Advocate Author of Seam Catch - Next Generation Java Exception Handling PGP key id: 926CCFF5 PGP key available at: keyserver.net, pgp.mit.edu
