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 <[email protected]> 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 <[email protected] > >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 <[email protected]> wrote: > > > > > 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 > > > > > > > > > > > -- > > 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
