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 01:17:32 GMT
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