If you’ve already installed the gem as described in the BUILD document, read on.
To use asciibuild on your Asciidoctor files, make sure you add the require flag to your invocation of asciidoctor or just use the asciibuild executable that was installed with the gem.
In a stock Asciidoctor file, this won’t do anything other than process the .adoc into a file in the abuild/ directory using your preferred backend (html by default). If you want asciibuild to EVAL your listing blocks, just add a style to them that conforms to the pattern [asciibuild,{lang}], where lang is either one of the built-in supported languages, or an executable that accepts input on STDIN. asciibuild will create a process based on the name of the interpreter in use (e.g. python) and pipe the content of the listing block into the process via STDIN. Any output (STD or ERR) is captured and written to the result document in the abuild/ directory.
asciibuild build.adoc
... output ...
open abuild/Currently, the built-in supported languages are described in the following list. Required settings are listed with {attribute} where the value must go and optional attributes are listed with their default settings.
-
Any interpreter that accepts
<STDIN>as input. Examples:bash,python, orruby.-
[asciibuild, bash] -
[asciibuild, python] -
[asciibuild, ruby]
-
-
Docker
-
[asciibuild, Dockerfile, image={name}, file="Dockerfile", overwrite=true, run=false, build_opts="", run_opts=""]For more on using the Docker support, visit the DOCKER document
-
-
docker-compose
-
[asciibuild, docker-compose, command=build, compose_opts="", file="docker-compose.yml"]
-
-
Erlang (via
escript)-
[asciibuild, erlang, escript_opts="", file="escript.erl"]
-
-
Makefile
-
[ascibuild, Makefile, target="", make_opts="", file="Makefile"]
-
-
Spark
-
Scala:
[asciibuild, spark-shell, spark_opts=""] -
Python:
[asciibuild, pyspark, spark_opts=""]
-
To use a bash or sh shell, add the [asciibuild,bash] or [asciibuild,sh] style to any listing block.
.Execute BASH in asciibuild
[source,bash]
[asciibuild,bash]
----
echo Hello `uname -s`
----|
Note
|
Default options when using bash are -exs. If you want to add additional options add an attribute of bash_opts="" to the [asciibuild] style.
|
asciibuild supports Apache Spark out-of-the-box. It supports both pyspark and spark-shell (Python and Scala, respectively). To use the Spark support in asciibuild, add a style of [asciibuild,pyspark] for PySpark or [asciibuild,spark-shell] for Scala.
This example is taken from the Spark documentation on using Python with Spark:
.Execute PySpark in asciibuild
[source,python]
[asciibuild,pyspark]
----
from pyspark import SparkContext
logFile = "README.adoc"
sc = SparkContext("local", "Simple App")
logData = sc.textFile(logFile).cache()
numAs = logData.filter(lambda s: 'a' in s).count()
numBs = logData.filter(lambda s: 'b' in s).count()
print("Lines with a: %i, lines with b: %i" % (numAs, numBs))
----asciibuild will support any language who’s executable accepts <STDIN> as input. If you can pipe content into it, you can use it in asciibuild. Here’s an example using Python:
.Execute Python in asciibuild
[source,python]
[asciibuild,python]
----
import subprocess
print "OS:"
subprocess.call(["uname", "-s"])
----|
Note
|
The styles [source,bash] and [source,python] are for the benefit of editors that recognize Asciidoc and will show source code formatting in a preview. asciibuild will add its own styles to the resulting blocks, regardless of what is set in the source document, so the generated document will be formatted correctly.
|
Output of commands described in asciibuild-enabled listing blocks is inserted directly into the rendered document, immediately following the block definition. If there is any output on <STDERR> it will also be rendered into the document. If the return code of the command is anything other than 0, the step will be marked as "in error" and subsequent steps will be skipped. A red warning icon will appear next to the step title to indicate the error. The following screenshot shows STDOUT and STDERR when an error occurs.
It’s possible to execute only a given set of blocks in an asciibuild document by setting the document attribute sections to a comma-separated list of regexes that will match section titles that should be executed. If a section title does not match one of these regexes, it will be marked in the resulting document as "skipped" with a yellow pause icon, as in the following example and screenshot.
Any section that starts with the name "Before All" or "After All" will always be run, regardless of the setting of sections. This is to provide setup and cleanup functionality. To get before and after functionality for a specific section, use a title like "Before My Section" and "After My Section". If you tell asciibuild to only execute "My Section", then it will also execute the "Before" and "After" sections as well.
|
Note
|
The fact that they are named "Before" and "After" is a semantic convenience only. Sections are executed in the order in which they appear in the document. |
asciibuild -a sections="Test Bash" test/test-block-processor.adoc
If you want to entirely skip the processing of listing block text through the Mustache template library, add an attribute to the listing block of template=false. This is helpful if you want to use things like Go templates, which use the same delimiters as Mustache templates.
.Execute Docker in asciibuild
[source,bash]
[asciibuild,bash,template=false]
----
docker inspect -q -f '{{.NetworkSettings.IPAddress}}' my-container
----If you want to use Go and Mustache templates in the same listing block, you can. You just have to set the Mustache delimiter to something other than {{ }}.
:my_container: my-container
.Execute Docker in asciibuild
[source,bash]
[asciibuild,bash,template=false]
----
# Reset Mustache tags since they conflict with Go templates
# {{=<% %>=}}
docker inspect -q -f '{{.NetworkSettings.IPAddress}}' <% my_container %>
----