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