deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Porter <lightguard...@gmail.com>
Subject Re: [jira] [Created] (DELTASPIKE-13) Choose documentation format and tools
Date Thu, 05 Jan 2012 03:53:55 GMT
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