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, 06 Jan 2012 20:36:16 GMT
i change my +0 to +1 (with the same prerequisites) because the apache cms
uses the reStructuredText format as well -> we just have to care about one
syntax.

imo: we should use our wiki (minimal syntax) to document the first parts
until we have a final agreement.

regards,
gerhard



2012/1/6 Gerhard Petracek <gerhard.petracek@gmail.com>

> thx john!
>
> +0 for trying it for some weeks to get a better impression, if it's ok for
> the sphinx team that we deploy the maven plugin to a public and stable
> maven repository (or they do it on their own).
>
> regards,
> gerhard
>
>
>
>
> 2012/1/5 Jason Porter <lightguard.jp@gmail.com>
>
>> I built the plugin and the site no problem without having jython
>> installed.
>> I think the original author is a little behind about jython [1], also his
>> version of sphinx he's shipping with a little behind [2]. We have full
>> control over how we want the templates to be laid out [3] and the themes
>> [4]. I took a look at the basic layout, it looks scary when you first look
>> at it, but if you're familiar with any of the template engines it's not
>> horrible. It's especially easy if you've used django. I think any of us
>> could figure it out fairly quickly (an hour or two maybe) and probably
>> come
>> up with a good theme in a day or so of focused development.
>>
>> [1]
>> http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jython-standalone%22
>> [2] http://sphinx.pocoo.org/
>> [3] http://sphinx.pocoo.org/templating.html
>> [4] http://sphinx.pocoo.org/theming.html
>>
>> On Wed, Jan 4, 2012 at 20:11, Jason Porter <lightguard.jp@gmail.com>
>> wrote:
>>
>> > I'll give things a try John. It looks like he's shading in jython. I'll
>> > try with a clean install, no jython and see what happens.
>> >
>> >
>> > On Wed, Jan 4, 2012 at 19:39, John D. Ament <john.d.ament@gmail.com
>> >wrote:
>> >
>> >> Hi All
>> >>
>> >> Gerhard asked me to help start digging in to this, since we have a bit
>> of
>> >> a
>> >> hold up on completing some features until we complete documentation
>> >> formats.  To start, I have setup the API docs to use sphinx + the
>> existing
>> >> maven-sphinx plugin.  Please ignore some of the changes I made, I was
>> >> trying to get the project to build.  I have only setup docs for the
>> >> core-api project, and even then it's a very simple doc, not robust but
>> >> shows off some of the plugin's features.  You can see the code at [1]
>> that
>> >> was used to generate the site.  If you want to regenerate for yourself,
>> >> you'll need these steps:
>> >>
>> >> 1. clone tom d's maven plugin from [2] and then build it.
>> >>
>> >> 2. From core-api, run mvn -Psphinx clean site
>> >>
>> >> 3. Launch in a browser your target/sphinx directory.
>> >>
>> >> Please understand that this by no means indicates a final way to do it,
>> >> but
>> >> only a first run at it.  All I did was copy most of the existing
>> structure
>> >> and import, then update some docs to reflect some deltaspike styled
>> >> content.  I added links to a few deltaspike pages.
>> >>
>> >> So, just some comments based on my usage:
>> >>
>> >> 1. The mark up syntax is a bit difficult to digest.  For me, it's
>> similar
>> >> to wiki markup, but different enough that it's frustrating.  See [3]
>> for a
>> >> quick ref as provided by Jason P.
>> >> 2. The build process seems a little difficult.  Requires jython, which
>> has
>> >> to be installed during the plugin build, since it seems like jython is
>> not
>> >> in maven.  The build of the site seems  to run pretty quick though.
>> >> 3. I don't think I have full control of the site.  The templates seem
>> to
>> >> have some hard formats, for example I couldn't update the upper right
>> >> index
>> >> link.  Some of the linking is also a bit confusing - why does the toc
>> >> function exist in index.rst vs other parts?
>> >> 4. The search feature is a good idea.  I don't know how well it is in
>> >> large
>> >> sites.
>> >> 5. Additional development needs to happen for a layout, color scheme.
>> >>
>> >> Regards,
>> >>
>> >> John
>> >>
>> >>
>> >> [1]
>> >>
>> >>
>> https://github.com/johnament/deltaspike-incubator/tree/master/deltaspike/core/api/src/site/sphinx
>> >> [2] https://github.com/tomdz/sphinx-maven
>> >> [3] http://docutils.sourceforge.net/docs/user/rst/quickref.html
>> >>
>> >>
>> >> On Sat, Dec 24, 2011 at 4:08 PM, Jason Porter <lightguard.jp@gmail.com
>> >> >wrote:
>> >>
>> >> > Just a follow up, there is at least one well known Java Project using
>> >> > Sphinx for documentation: Selenium, also Spock is using it, though
>> >> they're
>> >> > not building their docs as part of a CI job. A large list of projects
>> >> using
>> >> > Sphinx is also available at [1].
>> >> >
>> >> > The Selenium pom [2] uses antrun to call the build file (make, sh,
>> >> python,
>> >> > etc) for the docs. There's also readthedocs [3] which is interesting
>> and
>> >> > hosts the docs there.
>> >> >
>> >> > Some more info to think about. The project Dan and I linked to also
>> >> looks
>> >> > like it's fairly decent for what it does.
>> >> >
>> >> > [1] http://sphinx.pocoo.org/examples.html
>> >> > [2]
>> >> >
>> >> >
>> >>
>> http://code.google.com/p/selenium/source/browse/websites/www.seleniumhq.org/pom.xml
>> >> > [3] http://readthedocs.org/
>> >> >
>> >> > On Fri, Dec 23, 2011 at 12:50, Dan Allen <dan.j.allen@gmail.com>
>> wrote:
>> >> >
>> >> > > On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek
>> >> > > <gerhard.petracek@gmail.com>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
>> >> > >
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > 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
>> >
>>
>>
>>
>> --
>> 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