You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by Stephen Mallette <sp...@gmail.com> on 2015/06/08 19:06:34 UTC
Re: [TinkerPop] [TinkerPop3] AsciiDoc pre-processor reloaded
I will miss the fast run of the docs when I'm trying to just iterate on
some formatting problems or something like that, but it's worth it for
ensuring our docs stay current (without having to do that work manually
which was massively error prone and time consuming). Thanks for
this....good stuff!
On Mon, Jun 8, 2015 at 12:47 PM, Daniel Kuppitz <me...@gremlin.guru> wrote:
> Hello,
>
> we've been using the AsciiDoc pre-processor for quite a while now.
> However, it has had a few issues:
>
> - it wasn't possible to process code samples that make use of a plugin
> (e.g. neo4j)
> - it wasn't possible to execute console commands (e.g. :remote connect
> ...)
>
> These issues have now been resolved! Neo4j samples, Hadoop samples,
> Gremlin Server samples, everything is now being evaluated by the
> pre-processor. This way we can ensure, that almost all the code samples in
> the TinkerPop3 docs are always up to date and working.
>
> The bad news: pre-processing became lot slower.
> The good news: we've added progress bars; and watching slow processes with
> a progress bar is fun (at least the first few times :))
>
> This is how it looks like:
>
> daniel@cube /projects/apache/incubator-tinkerpop (master) $
> bin/process-docs.sh
>
> ==========================
> + Installing Plugins +
> ==========================
>
> * hadoop-gremlin ... done
> * neo4j-gremlin ... done
>
>
> ============================
> + Processing AsciiDocs +
> ============================
>
> * source: /projects/apache/incubator-tinkerpop/docs/src/index.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/index.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source: /projects/apache/incubator-tinkerpop/docs/src/preface.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/preface.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source: /projects/apache/incubator-tinkerpop/docs/src/intro.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/intro.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source:
> /projects/apache/incubator-tinkerpop/docs/src/the-graph.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graph.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source:
> /projects/apache/incubator-tinkerpop/docs/src/the-traversal.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-traversal.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source:
> /projects/apache/incubator-tinkerpop/docs/src/the-graphcomputer.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graphcomputer.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source:
> /projects/apache/incubator-tinkerpop/docs/src/gremlin-applications.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/gremlin-applications.asciidoc
> progress:
> [====================================================================================================]
> 100%
>
> * source:
> /projects/apache/incubator-tinkerpop/docs/src/implementations.asciidoc
> target:
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/implementations.asciidoc
> progress: [=====================================================>
> ] 53%
>
> ...
>
>
>
> Anyway, in my opinion the slow processing is not really a big problem as
> it's only done for a new release or when new features were added. Moreover
> should the benefit of having accurate code samples in the docs be worth the
> few extra minutes.
>
> Cheers,
> Daniel
>
> --
> You received this message because you are subscribed to the Google Groups
> "Gremlin-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to gremlin-users+unsubscribe@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com
> <https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>
Re: [TinkerPop] [TinkerPop3] AsciiDoc pre-processor reloaded
Posted by Daniel Kuppitz <me...@gremlin.guru>.
>
> oh - i forgot to ask - is that stuff all hooked into the
> bin/publish-docs.sh?
It is. bin/publish-docs.sh simply calls bin/process-docs.sh (which you will
usually use to test things locally).
Cheers,
Daniel
On Mon, Jun 8, 2015 at 7:07 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> oh - i forgot to ask - is that stuff all hooked into the
> bin/publish-docs.sh?
>
> On Mon, Jun 8, 2015 at 1:06 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I will miss the fast run of the docs when I'm trying to just iterate on
> > some formatting problems or something like that, but it's worth it for
> > ensuring our docs stay current (without having to do that work manually
> > which was massively error prone and time consuming). Thanks for
> > this....good stuff!
> >
> > On Mon, Jun 8, 2015 at 12:47 PM, Daniel Kuppitz <me...@gremlin.guru> wrote:
> >
> >> Hello,
> >>
> >> we've been using the AsciiDoc pre-processor for quite a while now.
> >> However, it has had a few issues:
> >>
> >> - it wasn't possible to process code samples that make use of a
> >> plugin (e.g. neo4j)
> >> - it wasn't possible to execute console commands (e.g. :remote
> >> connect ...)
> >>
> >> These issues have now been resolved! Neo4j samples, Hadoop samples,
> >> Gremlin Server samples, everything is now being evaluated by the
> >> pre-processor. This way we can ensure, that almost all the code samples
> in
> >> the TinkerPop3 docs are always up to date and working.
> >>
> >> The bad news: pre-processing became lot slower.
> >> The good news: we've added progress bars; and watching slow processes
> >> with a progress bar is fun (at least the first few times :))
> >>
> >> This is how it looks like:
> >>
> >> daniel@cube /projects/apache/incubator-tinkerpop (master) $
> >> bin/process-docs.sh
> >>
> >> ==========================
> >> + Installing Plugins +
> >> ==========================
> >>
> >> * hadoop-gremlin ... done
> >> * neo4j-gremlin ... done
> >>
> >>
> >> ============================
> >> + Processing AsciiDocs +
> >> ============================
> >>
> >> * source:
> /projects/apache/incubator-tinkerpop/docs/src/index.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/index.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >> /projects/apache/incubator-tinkerpop/docs/src/preface.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/preface.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> /projects/apache/incubator-tinkerpop/docs/src/intro.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/intro.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >> /projects/apache/incubator-tinkerpop/docs/src/the-graph.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graph.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >> /projects/apache/incubator-tinkerpop/docs/src/the-traversal.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-traversal.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >> /projects/apache/incubator-tinkerpop/docs/src/the-graphcomputer.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graphcomputer.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >>
> /projects/apache/incubator-tinkerpop/docs/src/gremlin-applications.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/gremlin-applications.asciidoc
> >> progress:
> >>
> [====================================================================================================]
> >> 100%
> >>
> >> * source:
> >> /projects/apache/incubator-tinkerpop/docs/src/implementations.asciidoc
> >> target:
> >>
> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/implementations.asciidoc
> >> progress: [=====================================================>
> >> ] 53%
> >>
> >> ...
> >>
> >>
> >>
> >> Anyway, in my opinion the slow processing is not really a big problem as
> >> it's only done for a new release or when new features were added.
> Moreover
> >> should the benefit of having accurate code samples in the docs be worth
> the
> >> few extra minutes.
> >>
> >> Cheers,
> >> Daniel
> >>
> >> --
> >> You received this message because you are subscribed to the Google
> Groups
> >> "Gremlin-users" group.
> >> To unsubscribe from this group and stop receiving emails from it, send
> an
> >> email to gremlin-users+unsubscribe@googlegroups.com.
> >> To view this discussion on the web visit
> >>
> https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com
> >> <
> https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com?utm_medium=email&utm_source=footer
> >
> >> .
> >> For more options, visit https://groups.google.com/d/optout.
> >>
> >
> >
>
Re: [TinkerPop] [TinkerPop3] AsciiDoc pre-processor reloaded
Posted by Stephen Mallette <sp...@gmail.com>.
oh - i forgot to ask - is that stuff all hooked into the
bin/publish-docs.sh?
On Mon, Jun 8, 2015 at 1:06 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> I will miss the fast run of the docs when I'm trying to just iterate on
> some formatting problems or something like that, but it's worth it for
> ensuring our docs stay current (without having to do that work manually
> which was massively error prone and time consuming). Thanks for
> this....good stuff!
>
> On Mon, Jun 8, 2015 at 12:47 PM, Daniel Kuppitz <me...@gremlin.guru> wrote:
>
>> Hello,
>>
>> we've been using the AsciiDoc pre-processor for quite a while now.
>> However, it has had a few issues:
>>
>> - it wasn't possible to process code samples that make use of a
>> plugin (e.g. neo4j)
>> - it wasn't possible to execute console commands (e.g. :remote
>> connect ...)
>>
>> These issues have now been resolved! Neo4j samples, Hadoop samples,
>> Gremlin Server samples, everything is now being evaluated by the
>> pre-processor. This way we can ensure, that almost all the code samples in
>> the TinkerPop3 docs are always up to date and working.
>>
>> The bad news: pre-processing became lot slower.
>> The good news: we've added progress bars; and watching slow processes
>> with a progress bar is fun (at least the first few times :))
>>
>> This is how it looks like:
>>
>> daniel@cube /projects/apache/incubator-tinkerpop (master) $
>> bin/process-docs.sh
>>
>> ==========================
>> + Installing Plugins +
>> ==========================
>>
>> * hadoop-gremlin ... done
>> * neo4j-gremlin ... done
>>
>>
>> ============================
>> + Processing AsciiDocs +
>> ============================
>>
>> * source: /projects/apache/incubator-tinkerpop/docs/src/index.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/index.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/preface.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/preface.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source: /projects/apache/incubator-tinkerpop/docs/src/intro.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/intro.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/the-graph.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graph.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/the-traversal.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-traversal.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/the-graphcomputer.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/the-graphcomputer.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/gremlin-applications.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/gremlin-applications.asciidoc
>> progress:
>> [====================================================================================================]
>> 100%
>>
>> * source:
>> /projects/apache/incubator-tinkerpop/docs/src/implementations.asciidoc
>> target:
>> /projects/apache/incubator-tinkerpop/target/postprocess-asciidoc/implementations.asciidoc
>> progress: [=====================================================>
>> ] 53%
>>
>> ...
>>
>>
>>
>> Anyway, in my opinion the slow processing is not really a big problem as
>> it's only done for a new release or when new features were added. Moreover
>> should the benefit of having accurate code samples in the docs be worth the
>> few extra minutes.
>>
>> Cheers,
>> Daniel
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "Gremlin-users" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to gremlin-users+unsubscribe@googlegroups.com.
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com
>> <https://groups.google.com/d/msgid/gremlin-users/CA%2Bf9seVN7JBNhbng%2BY5%2BkdGQrvx%2Bf6kPDvyt10jcRjr-MrAdQQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>> .
>> For more options, visit https://groups.google.com/d/optout.
>>
>
>