deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "John D. Ament" <john.d.am...@gmail.com>
Subject Re: [jira] [Created] (DELTASPIKE-13) Choose documentation format and tools
Date Thu, 05 Jan 2012 02:39:59 GMT
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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message