deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gerhard Petracek <gerhard.petra...@gmail.com>
Subject Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 04 May 2012 20:22:10 GMT
@ 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message