Starter project for Asciidoctor Gradle build

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Starter project for Asciidoctor Gradle build

Robert.Panzer
Hi,

Michael Hunger contacted me and asked for some help setting up a gradle project that

- builds documentation using the HTML and PDF backends
- includes tested code snippets (or validated queries in his particular case)

Other specialties include generating PDFs of manpages, slides (reveal.js or whatever) and refcards.

As these are things that I have no experience with yet either, I ask the community if anyone knows of an example project.
Imo in particular the first two points become more and more important.
Being able to say that the examples in the documentation are correct is sth that very much increases the confidence in the docs and the software as a whole as well, because it shows that folks really care about their docs.
Having a starter project that you could simply include as a submodule into your gradle build would help them to immediately concentrate on the content instead of fiddling around with the build.

If there is nothing available yet, would it be of interest to setup sth like that under the asciidoctor organization?
(Or even a lazybones template...)

Best regards,
Robert
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

asotobu
Hi there is already a lazybones template which configures asciidoctor gradle plugin with html and pdf output.

https://github.com/lordofthejars/decks/blob/master/springio/slides.adoc#tooling-gvm-laszybones-and-gradle
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

rwinch
In reply to this post by Robert.Panzer
There is also a suite of Asciidoctor Gradle Examples [1]. The closes example to what you are looking for is one that generates an HTML, PDF, and epub3 [2]. You can find the example outputs of the sample deployed here [3]. As requested, it also includes an example of including source code [4].

[1] https://github.com/asciidoctor/asciidoctor-gradle-examples/
[2] https://github.com/asciidoctor/asciidoctor-gradle-examples/tree/master/asciidoc-to-all-example
[3] http://asciidoctor.github.io/asciidoctor-gradle-examples/#_html_pdf_epub3_example
[4] http://asciidoctor.github.io/asciidoctor-gradle-examples/asciidoc-to-all-example/html5/example-manual.html#source-code

HTH,
Rob
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

asotobu
Yes this repo is awesome. I think it should converge to lazybones template. :)
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

Robert.Panzer
In reply to this post by rwinch
Wow, thank you!
That was fast! :)

So we're already all set!

Best regards,
Robert
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

rwinch
In reply to this post by asotobu
Great idea! I created a ticket to support lazybones [1].

[1] https://github.com/asciidoctor/asciidoctor-gradle-examples/issues/4
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

aalmiray
In reply to this post by Robert.Panzer
There's already a lazybones template that can be used to get started quickly with gradle + asciidoctor. It's linked to the central repository so there's no need for additional configuration. Simply invoke

    lazubones create asciidoctor-gradle myproject

et voilá!

https://bintray.com/aalmiray/kordamp/asciidoctor-gradle-template/view
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

rwinch
Thanks. I was just thinking it might be nice to have additional samples for lazybones. Perhaps we can move additional discussion to the linked github ticket.

Cheers,
Rob
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

mojavelinux
Administrator
In reply to this post by Robert.Panzer

Robert Panzer wrote:
So we're already all set!

+1000

The examples Rob and Danny have put together are a fantastic starting point for using Gradle to build Asciidoctor. And I'm confident it will continue to evolve over time.

Rob Winch wrote:
I was just thinking it might be nice to have additional samples for lazybones. Perhaps we can move additional discussion to the linked github ticket.

Agreed. I hope to see the research done in the maven-gradle-examples project feed into the lazybones template. Perhaps they can share code, or perhaps just ideas. But we definitely want to see the lazybones templates evolve to be able to create various starting points.

Cheers,
 
-Dan
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

mojavelinux
Administrator
In reply to this post by Robert.Panzer

On Sun, May 10, 2015 at 12:33 PM, Robert.Panzer [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Other specialties include generating PDFs of manpages, slides (reveal.js or whatever) and refcards.

The converter for generating manpages just got merged into Asciidoctor core {1}. You can then use the man and dvipdf tools to get to a PDF from there.

$ man -Tdvi ./command.1 > command.dvi
   dvipdf ./command.dvi

I'm sure Gradle could wrap that up.

Slides can be converted to pdf using deck2pdf. Cedric shows how he integrates it into his Gradle build {2}.

Rob and Danny, perhaps we can integrate Cedric's code snippet into the examples?

Refcards is a separate issue. The best solution here might be a custom converter using Prawn. You don't have to use Asciidoctor PDF to create the PDF...you can always just create your own converter using Prawn and get the exact layout you want (maybe reusing some bits).

That's the current state of the art as I know it :)

Of course, we have lots of work still to do on Asciidoctor PDF, but I'm finally getting a chance to get back to that now.

Cheers,

-Dan

Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

rwinch
Dan,

> Rob and Danny, perhaps we can integrate Cedric's code snippet into the examples?

Thanks for the suggestion! I created a new ticket to demonstrate deck2pdf [1]. I won't have time for a while, but I this way we don't lose track of it.

If any of the other ideas (i.e. manpages) make sense to add an example for, please feel free to create tickets.

NOTE: At the moment it seems that the jar is not deployed to a repository since it is relying on Maven Local, but perhaps I just need to dig around a bit.

[1] https://github.com/asciidoctor/asciidoctor-gradle-examples/issues/5

Cheers,
Rob
Reply | Threaded
Open this post in threaded view
|

Re: Starter project for Asciidoctor Gradle build

mojavelinux
Administrator

On Mon, May 11, 2015 at 9:16 AM, rwinch [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks for the suggestion! I created a new ticket to demonstrate deck2pdf [1]. I won't have time for a while, but I this way we don't lose track of it.

Super! I'll jump in if I get a chance.