deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pete Muir <pm...@redhat.com>
Subject Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 04 May 2012 20:39:41 GMT
My 2p.

Markdown is great for short docs e.g. README, CONTRIBUTING, RELEASE-PROCESS, and when you
just want to get something down. Setting up some of the fancy stuff like code highlighting,
nice formatting, table of contents is not very easy, I haven't yet found a good toolchain
wrapper for this. It's also missing some critical support e.g. tables.

Asciidoc is all round brilliant. It has everything you could need (supports everything docbok/latex
does), it comes with a good toolchain, built in code highlighting, toc etc.

Asciidoc doesn't have a java toolchain that I know of, so you are stuck with a native toolchain.
IMO not a problem, we can wrap it easily in bat/sh files.

On 4 May 2012, at 21:22, Gerhard Petracek wrote:

> @ our apache-cms experts:
> it would be nice if you share your experience at the previous thread (see
> [1]).
> 
> regards,
> gerhard
> 
> [1] http://s.apache.org/QIe
> 
> 
> 
> 2012/5/4 Jason Porter <lightguard.jp@gmail.com>
> 
>> 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) <
>> jira@apache.org> 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
>> 


Mime
View raw message