[ANN] Documentation effort and site redesign

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
51 messages Options
123456
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

catalan42
Hi - I haven't heard much on the Groovy documentation redesign for a bit, and thought I'd ask if any progress had been made.

I just saw a nice example from the Clojure community that might serve as a model for Groovy:  https://github.com/bbatsov/clojure-style-guide    This page shows a nice-looking example of documentation written in Markdown.

 The site also mentions the Transmuter tool (https://github.com/TechnoGate/transmuter) as a good way to convert Markdown into PDF or HTML (although I've not yet tried it myself).

Thoughts?
Alan Thompson

On Mon, Feb 11, 2013 at 7:36 AM, Guillaume Laforge
<[hidden email]> wrote:

> Right, Gradle went with Docbook, as far as I can see, and I think they added
> some layer for testing some of the snippets of code that are contained in
> the documentation.
>
> The "executable" aspect is important in my opinion, to keep the
> documentation as "alive" as possible, avoiding becoming out-dated quickly.
>
> But well, I'm not too fond of using XML for the documentation :-(
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

ChrLipp
Hello!

As mentioned, Gradle uses DocBook (see http://gradle.codehaus.org/How+to+build+the+documentation). On the mailing list they gave a good answer when asked if they are happy with it, see http://forums.gradle.org/gradle/topics/is_gradleware_happy_with_choosing_docbook_as_the_documentation_format

I would like to have a Groovy or Java based documentation build process and tool chain instead of using Ruby, Perl, Phyton and so on based tools. Not because they are not good enough, but I want to use and work with an complete and consistent eco system.
I would also prefer a lightweight documentation syntax instead of dealing with XML and I would like to get a result not only in HTML (single page and multi page) and PDF, but also epub and/or mobi.

Both Markdown and AsciiDoc provides these output formats. AsciiDoc generates Docbook and therefore is able to generate everything, but also Markdown allows epub generation via Markdown (see https://paulbradley.org/markdown-latex/ for example) with Pandoc.
AsciiDoc is not only Ruby, it provides also a Java library, see http://asciidoctor.org/news/2013/04/18/enjoy-the-magic-of-asciidoctor-in-java/

I would be happy with any lightweight language if I am not restricted to PDF and HTML only.
Regards, Christian
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
Hi,

On Fri, Apr 19, 2013 at 2:15 PM, ChrLipp <[hidden email]> wrote:
[...] 
As mentioned, Gradle uses DocBook (see
http://gradle.codehaus.org/How+to+build+the+documentation). On the mailing
list they gave a good answer when asked if they are happy with it, see
http://forums.gradle.org/gradle/topics/is_gradleware_happy_with_choosing_docbook_as_the_documentation_format

I'm not a big fag of writing documentation in XML as this is the case with DocBook, it's not very friendly, although as the post above mentions, yes, it's very toolable. 
 
I would like to have a Groovy or Java based documentation build process and
tool chain instead of using Ruby, Perl, Phyton and so on based tools. Not
because they are not good enough, but I want to use and work with an
complete and consistent eco system.

Those past days, I've been using AsciiDoc(tor) more and more, running various experiments for my requirements, and I must confess I'm really leaning towards using AsciiDoc(tor) now for the documentation.
The initial drawback of the solution was that the original AsciiDoc was a Python tool, so it was a no go for me as it means having the right Python installation available on developers' boxes, on CI, etc, so it was not practical at all.
But with AsciiDoctor, even if implemented in JRuby, it's much more usable, especially as there's even a Gradle plugin available! Which means we'll be able to integrate that in the Groovy build as I had hoped.
 
I would also prefer a lightweight documentation syntax instead of dealing
with XML and I would like to get a result not only in HTML (single page and
multi page) and PDF, but also epub and/or mobi.

AsciiDoctor seems to be a very good candidate for those requirements as well.
Some things aren't yet totally perfect there with both AsciiDoctor and the Gradle plugin, but some recent changes helped and we should be good with the next version of both.
 
Both Markdown and AsciiDoc provides these output formats. AsciiDoc generates
Docbook and therefore is able to generate everything, but also Markdown
allows epub generation via Markdown (see
https://paulbradley.org/markdown-latex/ for example) with Pandoc.
AsciiDoc is not only Ruby, it provides also a Java library, see
http://asciidoctor.org/news/2013/04/18/enjoy-the-magic-of-asciidoctor-in-java/
 
I had looked more at MarkDown in the first place, before looking into AsciiDoctor, but from my experiments, Markdown is more for individual documents, for pure markup, and less appropriate for full documentation (think applying custom stylesheets, including other documents/fragments/snippets, interlinking, etc).
AsciiDoc(tor) really seems a better fit.

I would be happy with any lightweight language if I am not restricted to PDF
and HTML only.

My main requirement is HTML and PDF, but AsciiDoc(tor) should help us for other formats as well
So we'll see how we progress along what other formats users want and how to generate them.
For ePub, for the time being, I think we still need to use the AsciiDoc Python backend though, but we can generate it manually and publish at each release as needed.

--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Russel Winder-3
On Fri, 2013-04-19 at 15:32 +0200, Guillaume Laforge wrote:
[…]
> I'm not a big fag of writing documentation in XML as this is the case with
> DocBook, it's not very friendly, although as the post above mentions, yes,
> it's very toolable.

I agree that authoring using DocBook/XML should be seen as the choice of
absolute last resort.

> Those past days, I've been using AsciiDoc(tor) more and more, running
> various experiments for my requirements, and I must confess I'm really
> leaning towards using AsciiDoc(tor) now for the documentation.

Have you tried Sphinx? It uses reStructuredText?

> The initial drawback of the solution was that the original AsciiDoc was a
> Python tool, so it was a no go for me as it means having the right Python
> installation available on developers' boxes, on CI, etc, so it was not
> practical at all.

Nothing wrong with using Python. Remember OSX comes with Python
installed but not Java.

> But with AsciiDoctor, even if implemented in JRuby, it's much more usable,
> especially as there's even a Gradle plugin available! Which means we'll be
> able to integrate that in the Groovy build as I had hoped.

If you are looking to use JRuby what is wrong with using Jython?

> AsciiDoctor seems to be a very good candidate for those requirements as
> well.
> Some things aren't yet totally perfect there with both AsciiDoctor and the
> Gradle plugin, but some recent changes helped and we should be good with
> the next version of both.

If you want to switch the Groovy project to use this, then it would be
wise to get a few others involved with the researching so as to have a
core of people who know how to use it.

> I had looked more at MarkDown in the first place, before looking into
> AsciiDoctor, but from my experiments, Markdown is more for individual
> documents, for pure markup, and less appropriate for full documentation
> (think applying custom stylesheets, including other
> documents/fragments/snippets, interlinking, etc).

I would agree with this. MarkDown is not a tool for big documents, at
least no at this time.

> AsciiDoc(tor) really seems a better fit.

Debian Unstable comes with AsciiDoc 8.6.7 so I can chip in with some
bits and pieces if that would help.

> My main requirement is HTML and PDF, but AsciiDoc(tor) should help us for
> other formats as well
> So we'll see how we progress along what other formats users want and how to
> generate them.
> For ePub, for the time being, I think we still need to use the AsciiDoc
> Python backend though, but we can generate it manually and publish at each
> release as needed.

Nothing wrong with Python so don't worry about using it.

Pandoc knows about AsciiDoc.


--
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:[hidden email]
41 Buckmaster Road    m: +44 7770 465 077   xmpp: [hidden email]
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
Hi Russel,

On Fri, Apr 19, 2013 at 6:59 PM, Russel Winder <[hidden email]> wrote:
[…]
I agree that authoring using DocBook/XML should be seen as the choice of
absolute last resort.

Yeah :-)
At least, you know, it's not a binary format either, so it'd still work correctly for things like "diffs" and such.
But still, DocBook/XML feels a bit backward nowadays ;-)
Furthermore, another reason I was looking at Markdown and AsciiDoc was that they're viewable "rendered" on GitHub, so it's quite handy for contributions (also because of the "edit in place" feature, so that users can easily contribute to the documentation, even if only for typos.
 
[...]
Have you tried Sphinx? It uses reStructuredText?

Only briefly.
It seemed interesting too.
I don't think it was supported by GitHub, but I might be wrong.
Also, for the build automation (see further down), it might not be ideal.
 
[...]
Nothing wrong with using Python. Remember OSX comes with Python
installed but not Java.

But Java doesn't come with Python AFAIK.
So folks cloning Groovy would have difficulties with the documentation build step, as it might mean requiring a full blown (and properly configured) Python available on the system.
 
[...]
If you are looking to use JRuby what is wrong with using Jython?

I've got nothing against neither (P|J)ython nor J?Ruby!
My sole worry here is that it can be easily integrated in our build process.
 
[...]
If you want to switch the Groovy project to use this, then it would be
wise to get a few others involved with the researching so as to have a
core of people who know how to use it.

 
[...]
I would agree with this. MarkDown is not a tool for big documents, at
least no at this time.

And it doesn't seem to evolve in that direction anyway.
 
[...]
Debian Unstable comes with AsciiDoc 8.6.7 so I can chip in with some
bits and pieces if that would help.

Any help will be appreciated obviously at any level ;-)
I'll need to make a little status report on all that for sure.
We should also have soon some first elements for the design of the website.

Back to AsciiDoc, AsciiDoc(tor) seems to becoming as much as possible compliant with the original AsciiDoc, but it also adds new bits, for example some partial inclusion mechanism which is not available in the original.

So far, from my experiments, I think the Groovy website will end up being a mix of static html content, and some generated content. We'll have to have also a bit of dynamic content for the blog part.
 
[...]
Nothing wrong with Python so don't worry about using it.

Pandoc knows about AsciiDoc.

Yeah Pandoc is also an interesting tool, but again, for the generated (and executable) documentation, I worry about the integration in our build. So whatever solution we'd chose (very likely AsciiDoc(tor) at this point) should be easy to integrate in our Gradle build, and shouldn't cause trouble for developers (like having to have a Python or Ruby environment on their machine).


--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

AW: [groovy-user] Re: [ANN] Documentation effort and site redesign

Jochen Eddelbüttel

Hi Guillaume,

 

I’ve just browsed through a bit of the AsciiDoc documentation. Definitely much more advanced stuff than Markdown, but still with a fairly low entry barrier. It’s got some sugar that’ll sweeten the transition. I don’t think it would scare away too many potential contributors. I’ve got a small German language Groovy tutorial in the making and I might do an AsciiDoc Prototype.

 

My Groovy evangelism session at work went well on Thursday, getting the word out about Groovlets, Groovy-SQL, Groovy-JSON and a bit of meta programming.

 

Jochen (Eddel+)

 

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Miro Bezjak


On Sat, Apr 20, 2013 at 8:33 AM, Jochen Eddelbüttel <[hidden email]> wrote:

Hi Guillaume,

 

I’ve just browsed through a bit of the AsciiDoc documentation. Definitely much more advanced stuff than Markdown, but still with a fairly low entry barrier. It’s got some sugar that’ll sweeten the transition. I don’t think it would scare away too many potential contributors. I’ve got a small German language Groovy tutorial in the making and I might do an AsciiDoc Prototype.

 

My Groovy evangelism session at work went well on Thursday, getting the word out about Groovlets, Groovy-SQL, Groovy-JSON and a bit of meta programming.

 

Jochen (Eddel+)

 


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
Good to know, thanks Miro.

Out of curiosity, do you know if there's a Java library for that format?
(something that could somehow be integrated in our Gradle build, which should thus be JVM friendly)

I probably won't change my mind as AsciiDoc seems to nicely fit the bill, but that's good to know nonetheless how far we can't integrate ReStructuredText / Sphinx in the context of a Java project.

Guillaume


On Sun, Apr 21, 2013 at 3:01 PM, Miro Bezjak <[hidden email]> wrote:


On Sat, Apr 20, 2013 at 8:33 AM, Jochen Eddelbüttel <[hidden email]> wrote:

Hi Guillaume,

 

I’ve just browsed through a bit of the AsciiDoc documentation. Definitely much more advanced stuff than Markdown, but still with a fairly low entry barrier. It’s got some sugar that’ll sweeten the transition. I don’t think it would scare away too many potential contributors. I’ve got a small German language Groovy tutorial in the making and I might do an AsciiDoc Prototype.

 

My Groovy evangelism session at work went well on Thursday, getting the word out about Groovlets, Groovy-SQL, Groovy-JSON and a bit of meta programming.

 

Jochen (Eddel+)

 





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Miro Bezjak
I can't say that I do. I have used sphinx on a couple of JVM projects - always with python and (generated) makefile.

I understand you are trying to lower the bar and thus receive more contributions. I've never used AsciiDoc so I can't compare it with sphinx but I can attest that sphinx is a very capable documentation system. Perhaps it is worth considering it even if it means requiring something other than gradle|maven|ant.

Regards,
Miro


On Sun, Apr 21, 2013 at 8:29 PM, Guillaume Laforge <[hidden email]> wrote:
Good to know, thanks Miro.

Out of curiosity, do you know if there's a Java library for that format?
(something that could somehow be integrated in our Gradle build, which should thus be JVM friendly)

I probably won't change my mind as AsciiDoc seems to nicely fit the bill, but that's good to know nonetheless how far we can't integrate ReStructuredText / Sphinx in the context of a Java project.

Guillaume


On Sun, Apr 21, 2013 at 3:01 PM, Miro Bezjak <[hidden email]> wrote:


On Sat, Apr 20, 2013 at 8:33 AM, Jochen Eddelbüttel <[hidden email]> wrote:

Hi Guillaume,

 

I’ve just browsed through a bit of the AsciiDoc documentation. Definitely much more advanced stuff than Markdown, but still with a fairly low entry barrier. It’s got some sugar that’ll sweeten the transition. I don’t think it would scare away too many potential contributors. I’ve got a small German language Groovy tutorial in the making and I might do an AsciiDoc Prototype.

 

My Groovy evangelism session at work went well on Thursday, getting the word out about Groovlets, Groovy-SQL, Groovy-JSON and a bit of meta programming.

 

Jochen (Eddel+)

 





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

ChrLipp
I would appreciate if you choose AsciDoc(tor). I didn't know the gradle plugin and did already some tests over the weekend. A zero installation build - having just to execute 'gradlew' - is a huge advantage.

There are a lot of books written in AsciiDoc, see http://www.methods.co.nz/asciidoc/index.html#X6
Matt Neuburg describes his toolchain (on Mac) here: http://www.apeth.net/matt/iosbooktoolchain.html

And since the output is DocBook I will be able to port it to epub. Prepare to receive a pull request :-)

Regards, Christian
123456
Loading...