[DISCUSS] Better GLV Support in Documentation

[Stephen Mallette <sp...@gmail.com>]

I happened to turn a splinter of an idea over the weekend into something
that was almost fully working only to find out that someone else had
already done the work better than me - oh well, the good news is that we
can now generate this kind of documentation:

https://imgur.com/a/bTdUO

I think that will be a big help to users who come from other languages
(with the rise of GLVs) and say...."ugh, it's all Groovy, where is the <my
language> stuff?" Unfortunately, I don't think they are making the
connection that it's all just Gremlin. Anyway, I think it would be neat if
we slowly started migrating the documentation toward something for GLV
centric and less so heavily focused on Java and this would be an easy good
start.

Note that ultimately, the goal here is to not dynamically eval() every
snippet of Gremlin in every language. I think we will have a "Console" tab
and a "Groovy" tab, followed by whatever tabs we add additional docs for.
The "Console" tab will be the Groovy Console output as we have now and the
other tabs will just have the raw code (without execution). That way, you
can look at the execution on the Console tab first then see the syntax in
your favorite language.

I've pushed the work so far to this branch

https://github.com/apache/tinkerpop/tree/TINKERPOP-1447

so that I can get a little help from Kuppitz with his pre-processor stuff
for the Console tab to generate properly. Anyway, thoughts welcome on
what's there so far.

Re: [DISCUSS] Better GLV Support in Documentation

[Stephen Mallette <sp...@gmail.com>]

I had a word with Gruno before I made to propose anything here regarding
how to release our tool. His opinion was that this module was effectively a
subproject of TinkerPop and therefore same release rules applied. That
perspective made me realize that we really don't need some special release
process for it and that it should just release as part of our standard
process. If we need some fix to the tool independent of standard release we
can just do a release candidate version. I think that should work.

On Tue, Dec 5, 2017 at 4:15 PM, Stephen Mallette <sp...@gmail.com>
wrote:

> I just thought I'd point out that to make this work I had to create a new
> module:
>
> https://github.com/apache/tinkerpop/tree/TINKERPOP-1447/
> docs/utils/asciidoctor-extensions
>
> This module acts as a plugin to the asciidoctor build. I currently have it
> disconnected from the TinkerPop root pom as it really doesn't have anything
> to do with our "graph" code. I also thought that we may find that it is
> necessary to release that code independently of the main part of the
> repository (in case there is a problem with general doc generation). I'm
> not sure what the process is for releasing this "tool" as it is independent
> from what TinkerPop is about. I guess I will try to find some information
> on that. If you think this should be handled a different way, please let me
> know.
>
>
>
>
> On Mon, Dec 4, 2017 at 3:42 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
>> I happened to turn a splinter of an idea over the weekend into something
>> that was almost fully working only to find out that someone else had
>> already done the work better than me - oh well, the good news is that we
>> can now generate this kind of documentation:
>>
>> https://imgur.com/a/bTdUO
>>
>> I think that will be a big help to users who come from other languages
>> (with the rise of GLVs) and say...."ugh, it's all Groovy, where is the <my
>> language> stuff?" Unfortunately, I don't think they are making the
>> connection that it's all just Gremlin. Anyway, I think it would be neat if
>> we slowly started migrating the documentation toward something for GLV
>> centric and less so heavily focused on Java and this would be an easy good
>> start.
>>
>> Note that ultimately, the goal here is to not dynamically eval() every
>> snippet of Gremlin in every language. I think we will have a "Console" tab
>> and a "Groovy" tab, followed by whatever tabs we add additional docs for.
>> The "Console" tab will be the Groovy Console output as we have now and the
>> other tabs will just have the raw code (without execution). That way, you
>> can look at the execution on the Console tab first then see the syntax in
>> your favorite language.
>>
>> I've pushed the work so far to this branch
>>
>> https://github.com/apache/tinkerpop/tree/TINKERPOP-1447
>>
>> so that I can get a little help from Kuppitz with his pre-processor stuff
>> for the Console tab to generate properly. Anyway, thoughts welcome on
>> what's there so far.
>>
>>
>>
>

Re: [DISCUSS] Better GLV Support in Documentation

[Stephen Mallette <sp...@gmail.com>]

I just thought I'd point out that to make this work I had to create a new
module:

https://github.com/apache/tinkerpop/tree/TINKERPOP-1447/docs/utils/asciidoctor-extensions

This module acts as a plugin to the asciidoctor build. I currently have it
disconnected from the TinkerPop root pom as it really doesn't have anything
to do with our "graph" code. I also thought that we may find that it is
necessary to release that code independently of the main part of the
repository (in case there is a problem with general doc generation). I'm
not sure what the process is for releasing this "tool" as it is independent
from what TinkerPop is about. I guess I will try to find some information
on that. If you think this should be handled a different way, please let me
know.




On Mon, Dec 4, 2017 at 3:42 PM, Stephen Mallette <sp...@gmail.com>
wrote:

> I happened to turn a splinter of an idea over the weekend into something
> that was almost fully working only to find out that someone else had
> already done the work better than me - oh well, the good news is that we
> can now generate this kind of documentation:
>
> https://imgur.com/a/bTdUO
>
> I think that will be a big help to users who come from other languages
> (with the rise of GLVs) and say...."ugh, it's all Groovy, where is the <my
> language> stuff?" Unfortunately, I don't think they are making the
> connection that it's all just Gremlin. Anyway, I think it would be neat if
> we slowly started migrating the documentation toward something for GLV
> centric and less so heavily focused on Java and this would be an easy good
> start.
>
> Note that ultimately, the goal here is to not dynamically eval() every
> snippet of Gremlin in every language. I think we will have a "Console" tab
> and a "Groovy" tab, followed by whatever tabs we add additional docs for.
> The "Console" tab will be the Groovy Console output as we have now and the
> other tabs will just have the raw code (without execution). That way, you
> can look at the execution on the Console tab first then see the syntax in
> your favorite language.
>
> I've pushed the work so far to this branch
>
> https://github.com/apache/tinkerpop/tree/TINKERPOP-1447
>
> so that I can get a little help from Kuppitz with his pre-processor stuff
> for the Console tab to generate properly. Anyway, thoughts welcome on
> what's there so far.
>
>
>