screenshot plugin for asciidoctor

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

screenshot plugin for asciidoctor

fix
This post was updated on .
Hi guys

I have just released a gradle plugin to automate your screenshots in asciidoctor
http://fix.github.io/asciidoctor-screenshot/

It is simple and powerful i think
It leverages the awesome geb library

I would some help
- to package it as a gradle plugi
- create more examples
- add more frames/options

I have also started some proof of concept to drive BDD towards what can be called DDD Documentation Driven Development. It is some kind of supercharged cucumber with asciidoctor and this screenshot plugin

The idea is to write documentation before and validate and complete on development stage.

I would welcome some cuke mastermind to givr me a hand

Cheers
Reply | Threaded
Open this post in threaded view
|

Re: screenshot plugin for asciidoctor

mojavelinux
Administrator
FX,

This is really fantastic! It's exactly the type of integration between automation and documentation that we want to encourage to help keep documents up to date and integrated with the application's functionality!

I'd like to make a few suggestions that will help align the extension syntax with the AsciiDoc convention.

First, the title of the image block should be read from the title attribute instead of the body of the block. For example, instead of writing:

[source,asciidoc]
----

[screenshot, name=google, url=http://google.com, dimension=FRAME_IMAC]
The Google landing page

----

We'd want:

[source,asciidoc]
----

.The Google landing page
[screenshot, name=google, url=http://google.com, dimension=FRAME_IMAC]

----

You can access the title from the attributes map that is passed to the extension.

However, it becomes clear that since we have no text in the block, it won't get processed. That's why I think "screenshot" should be a block macro instead of a block. (Thus, we'd need two extensions instead of one).

[source,asciidoc]
----

.The Google landing page
screenshot::[name=google, url=http://google.com, dimension=FRAME_IMAC]

----

Block macros tend to follow the pattern <name>::<target>[<attributes>], so we'd want to move the URL to the <target> location. That gives us:

[source,asciidoc]
----

.The Google landing page
screenshot::http://google.com[name=google,dimension=FRAME_IMAC]

----

That leaves us with the "action" blocks. I think perhaps we should either assume that a screenshot block (not block macro) is an action, or we rename it to something like "browse" to indicate it's driving a browser (perhaps we can drive a browser for other purposes, like tests).

[source,asciidoc]
----

[browse]
....
$("input", name: "q").value("asciidoctor")
waitFor(5){true}
....

----

I think the "browse" should be registered on literal blocks in addition to paragraphs, with the literal block being the preferred syntax (as shown in the previous example). That keeps the text from being interpreted in the absence of the extension (like on GitHub).

You might also want to consider the use of positional attributes for any required attributes to make the syntax simpler. For instance, you could make the dimensions of the window the first positional attribute on the "browse" block:

[source,asciidoc]
----

[browse,iphone5]
....
$("input", name: "q").value("asciidoctor")
waitFor(5){true}
....

----

Notice I used the value "iphone5" instead of FRAME_IPHONE5. I think you could do the conversion automatically.

Again, this is great stuff!

Once you converted the project to a standalone extension, I think it would be a great addition for the Asciidoctor org on GitHub. Since the extension is written for Java, I recommend naming it asciidoctorj-screenshot. In the future, we could have a Ruby version too.

Cheers,

-Dan

On Mon, Aug 25, 2014 at 2:16 PM, fix [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi guys

I have just released a gradle plugin to automate your screenshots in asciidoctor
http://fix.github.io/asciidoctor-screenshot/

It is simple and powerful i think
It leverages the awesome geb library

I would some help
- to package it as a gradle plugi
- create more examples
- add more frames/options

Cheers


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/screenshot-plugin-for-asciidoctor-tp2072.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
fix
Reply | Threaded
Open this post in threaded view
|

Re: screenshot plugin for asciidoctor

fix
Hi Dan, thanks for the feedback,

I have to say I agree most of your comments, I felt that the block processing was a bit awkward. I' am doing the necessary changes.

I need however a few hints :
- how to make it as a full asciidoctorj plugin? The only example I have (and i started from) is the pig latin plugin released by andres, which is incomplete in that rescpect. Any hint welcome.
- Also, as you may see in the source code, I use a hack to be able to frame correctly the screenshots (iphone, imac etc...), using the "alt" arg of the  tag to apply css. I have not discovered (I do think this is unaccessible) a way to hook in "class".


Cheers,
Fix

Reply | Threaded
Open this post in threaded view
|

Re: screenshot plugin for asciidoctor

mojavelinux
Administrator
Excellent!

On Sun, Sep 21, 2014 at 6:54 AM, fix [via Asciidoctor :: Discussion] <[hidden email]> wrote:
- how to make it as a full asciidoctorj plugin? The only example I have (and i started from) is the pig latin plugin released by andres, which is incomplete in that rescpect. Any hint welcome.

Alex has several examples of extensions for AsciidoctorJ in his extension repo {1}. (We should be migrating those into the Asciidoctor organization soon.)

- Also, as you may see in the source code, I use a hack to be able to frame correctly the screenshots (iphone, imac etc...), using the "alt" arg of the  tag to apply css. I have not discovered (I do think this is unaccessible) a way to hook in "class". 

Aha, that's an easy one. The "role" attribute becomes the "class" attribute in the HTML output.  Pass it to the createBlock method {2} when you create the image.

Cheers,

-Dan

Reply | Threaded
Open this post in threaded view
|

Re: screenshot plugin for asciidoctor

wimalopaan
In reply to this post by fix
Hi all,

is there a chance to use this plugin with asciidoctor? I think its only a plugin for asciidoctorJ ?

Reply | Threaded
Open this post in threaded view
|

Re: screenshot plugin for asciidoctor

mojavelinux
Administrator

On Wed, Mar 18, 2015 at 11:54 AM, wimalopaan [via Asciidoctor :: Discussion] <[hidden email]> wrote:
is there a chance to use this plugin with asciidoctor? I think its only a plugin for asciidoctorJ ?

Currently it's only for AsciidoctorJ. This is definitely something to consider when writing plugins. Plugins written in Java can't (easily) be used from Ruby (perhaps there is a way). The other way around is very possible.

I suppose the plugin would need to be rewritten in Ruby if you want to use it from there. But at least the logic is done so it's just a matter of porting the code.