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
