Dan, I also like the results Andrew and Aslak had with that for the new Arquillian page.
Could you probably provide a skeleton and sample integration which we can tweak? Best would be if you just create a git-clone and provide that on github. then we play around with it and if it turns out to be good, then we can just push this branch to ds.asf:master wdyt? LieGrue, strub ----- Original Message ----- > From: Gerhard Petracek <[email protected]> > To: [email protected] > Cc: > Sent: Friday, December 23, 2011 9:20 PM > Subject: Re: [jira] [Created] (DELTASPIKE-13) Choose documentation format and > tools > > hi dan, > > i said: >if< there are too many open questions right now,... > > we already discussed that we would use as few docbook-tags as possible (in > any case). > however, we are going to commit features quite soon and i would prefer to > have at least the basic descriptions in the repository from the very > beginning (instead of just waiting until this topic is resolved). > > regards, > gerhard > > > > 2011/12/23 Dan Allen <[email protected]> > >> On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek >> <[email protected]>wrote: >> >> > 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. >> > >> >> Choosing docbook for this reason seems like just giving up before the match >> begins. Jason is absolutely right that docbook is a huge barrier to open >> source contributions and totally overkill/bloatware for writing sentences. >> Sphinx allows you to do just that, write sentences. No B.S. No special >> editor. No angled brackets. Just type. It's essentially markdown, or a >> variant of it [1], put into a scaffolding for a book. >> >> The Maven plugin seems very up to date and I really doubt there will be >> much trouble to get it to run [2]. >> >> With Sphinx, you are going to get better docs from day one. Any project >> should jump at that prospect, given how notorious projects are for having >> bad docs. >> >> "Sphinx is a tool that makes it easy to create intelligent and > beautiful >> documentation" >> >> Btw, we aren't necessarily advocating for Sphinx as we are advocating > for >> writing docs in plain text. Sphinx just happens to offer the best >> scaffolding for that purpose. And proven. >> >> -Dan >> >> [1] >> >> > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#quick-syntax-overview >> [2] https://github.com/tomdz/sphinx-maven/blob/master/README.md >> >> -- >> Dan Allen >> Principal Software Engineer, Red Hat | Author of Seam in Action >> Registered Linux User #231597 >> >> http://www.google.com/profiles/dan.j.allen#about >> http://mojavelinux.com >> http://mojavelinux.com/seaminaction >> >
