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] [Created] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 23 Dec 2011 18:18:59 GMT
if there are too many open questions right now, i would suggest that we
start with docbook and evaluate the alternatives within the next weeks.

regards,
gerhard


2011/12/20 Gerhard Petracek <gerhard.petracek@gmail.com>

> +0 for trying sphinx, if we have a working maven-plug-in (without
> installing it manually) and we can use our jenkins nodes to generate the
> documentation.
>
> regards,
> gerhard
>
>
>
> 2011/12/20 Jason Porter <lightguard.jp@gmail.com>
>
>> There's this: https://github.com/tomdz/sphinx-maven
>>
>> If not, I'm sure we can write our own. If we with Sphinx then the
>> question is CPython or Jython for running it. It also looks like there's an
>> ant task wen you go the Jython route.
>>
>> Markdown would be fine, but what would you use to create other kinds of
>> output? I also don't think Markdown has enough richness for documentation.
>>
>> As for the Confluence thing, it's a JBoss Confluence extension, so we'd
>> have to install it. It also doesn't allow for the docs to be easily stored
>> with the code.
>>
>> Sent from my iPhone
>>
>> On Dec 20, 2011, at 6:01, Antoine Sabot-Durand <antoine@sabot-durand.net>
>> wrote:
>>
>> > Sphinx looks nice but is there a maven plugin ?
>> >
>> > What about Markdown format, it's becoming very popular ?
>> >
>> > I know it's not directly manage by maven, but wasn't confluence
>> supposed to help generate docbook format from wiki pages ? It could be a
>> good way to keep docbook but have a nice way to generate it painlessly.
>> >
>> > +1 to have something easier than docbook or some optional helper to
>> generate it.
>> >
>> > Antoine SABOT-DURAND
>> >
>> > Le 16 déc. 2011 à 01:01, Jason Porter a écrit :
>> >
>> >> Shane's probably tired of hearing me harp on docbook, oh well :)
>> >>
>> >> Here's a tool that's nice to use, output is good and it has a great
>> >> community following: http://sphinx.pocoo.org/ If we want to look into
>> it,
>> >> great, if we go back to docbook, great, I'll stop complaining and just
>> use
>> >> it.
>> >>
>> >> Buildable docs is fine, if we have to craft a maven plugin, fine.
>> >>
>> >> +1 for a set of a allowed docbook elements should we go with docbook
>> >>
>> >> +1 for continuing discussions on the mailing list.
>> >>
>> >> On Thu, Dec 15, 2011 at 16:53, Gerhard Petracek
>> >> <gerhard.petracek@gmail.com>wrote:
>> >>
>> >>> +1 for "buildable docs" if we keep the documentation inside the git
>> >>> repository.
>> >>> -1 for anything else than a maven plugin. if we don't have one for the
>> >>> documentation tool, we can impl. it (or we use a different tool).
>> >>> (+0 for docbook) +1 for an alternative, >if< it makes sense.
>> >>>
>> >>> @discussions:
>> >>> +1 for continuing to use the mailing list for the main discussion/s
-
>> it's
>> >>> easier to follow, mirrored, ... .
>> >>>
>> >>> regards,
>> >>> gerhard
>> >>>
>> >>>
>> >>>
>> >>> 2011/12/16 Jason Porter <lightguard.jp@gmail.com>
>> >>>
>> >>>> We haven't been discussing other issues on jira, but on the mailing
>> list.
>> >>>>
>> >>>> Sent from my iPhone
>> >>>>
>> >>>> On Dec 15, 2011, at 16:31, Shane Bryzak <sbryzak@gmail.com>
wrote:
>> >>>>
>> >>>>> You need to add your objections to the issue ;)
>> >>>>>
>> >>>>> Buildable by Maven just means we can build the documentation
as
>> part of
>> >>>> the
>> >>>>> standard project build/release process.
>> >>>>>
>> >>>>> On Fri, Dec 16, 2011 at 9:25 AM, Jason Porter <
>> lightguard.jp@gmail.com
>> >>>>> wrote:
>> >>>>>
>> >>>>>> -1 to DocBook it's difficult to get people up to speed and
is a
>> turn
>> >>> off
>> >>>>>> for new contributors.
>> >>>>>>
>> >>>>>> Also what exactly do you mean by "buildable with maven"?
Does that
>> >>> mean
>> >>>> we
>> >>>>>> need a plugin? Can an ant task or other scripting work?
>> >>>>>>
>> >>>>>> On Thu, Dec 15, 2011 at 15:39, Shane Bryzak (Created) (JIRA)
<
>> >>>>>> jira@apache.org> wrote:
>> >>>>>>
>> >>>>>>> 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: Gerhard Petracek
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> 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
>> >>>>>>
>> >>>>
>> >>>
>> >>
>> >>
>> >>
>> >> --
>> >> 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