This is an automated email from the ASF dual-hosted git repository.
bdelacretaz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
The following commit(s) were added to refs/heads/master by this push:
new 267ca35 Clarify README and add Vega diagram example
267ca35 is described below
commit 267ca35c88b383b485d2ff5d4acef1b9c70b91a2
Author: Bertrand Delacretaz <[email protected]>
AuthorDate: Mon Aug 31 13:41:26 2020 +0200
Clarify README and add Vega diagram example
---
asciidoctor-diagrams/README.md | 48 ++++--
.../src/docs/generated-diagrams/vega-example.svg | 3 +
.../src/main/asciidoc/more-diagrams.adoc | 189 +++++++++++++++++++++
3 files changed, 223 insertions(+), 17 deletions(-)
diff --git a/asciidoctor-diagrams/README.md b/asciidoctor-diagrams/README.md
index c268e1b..ab1222c 100644
--- a/asciidoctor-diagrams/README.md
+++ b/asciidoctor-diagrams/README.md
@@ -8,8 +8,12 @@ in README and other Markdown files. It is based on the
Asciidoctor Diagram is a set of Asciidoctor extensions
that support generating diagrams from multiple diagram
-languages including AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag,
NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax,
UMLet, Vega, Vega-Lite and WaveDrom. See [their
website](https://asciidoctor.org/docs/asciidoctor-diagram/) website
-for more details.
+languages including AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag,
NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax,
UMLet, Vega, Vega-Lite and WaveDrom.
+
+See [their website](https://asciidoctor.org/docs/asciidoctor-diagram/) website
+for more details. Many of these tools do not work out of the box and must be
installed
+separately to be available at build time, but a few them are available out of
the box, see
+below.
We might include this plugin configuration in the Sling Parent POM if we start
using it in several
modules.
@@ -27,29 +31,39 @@ Markdown files.
Here are example diagrams generated by the asciidoc documents found under
`src/docs/asciidoc`
in this project.
-Note that some extensions require installing specific binaries, like Graphviz
in this example. Others
-are built-in and require nothing from the environment besides a standard Maven
setup.
+### Out-of-the box tools
+
+The following diagram generation tools should work on a standard Maven setup.
-### ditaa diagram
+#### ditaa diagram
-### GraphViz diagram
-This one requires the `dot` command of Graphviz to be available at build time.
+#### PlantUML diagram
-
+
+
+#### PlantUML diagram from a different source file
-If it is missing you probably got the following error at build time:
+
- asciidoctor: ERROR: more-diagrams.adoc: line 2: Failed to generate image:
- Could not find the 'dot' executable in PATH; add it to the PATH or specify
- its location using the 'graphvizdot' document attribute
+### Tools that must be installed separately
-See the pom for how to change the location of the `dot` executable, if needed.
+The following diagram generation tools must be installed separately to be
available
+at build time. If they are missing, the Maven plugin outputs descriptive
+error messages but does not fail the build.
-### PlantUML diagram
+The `more-syntaxes.adoc` document has more examples in various syntaxes,
+most or all fail to build unless you have installed the required tools.
-
+#### GraphViz diagram
+This one requires the `dot` command of [Graphviz](https://graphviz.org/)
+to be available at build time.
-### PlantUML diagram from a different source file
+
+
+#### Vega diagram
-
+[Vega](https://vega.github.io) can be installed with `npm install -g vega-cli`
so
+that might be a reasonable option if we need more complex diagrams.
+
+
diff --git a/asciidoctor-diagrams/src/docs/generated-diagrams/vega-example.svg
b/asciidoctor-diagrams/src/docs/generated-diagrams/vega-example.svg
new file mode 100644
index 0000000..ddc64e7
--- /dev/null
+++ b/asciidoctor-diagrams/src/docs/generated-diagrams/vega-example.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd";>
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; version="1.1" class="marks"
width="400" height="400" viewBox="0 0 400 400"><g fill="none"
stroke-miterlimit="10" transform="translate(40,40)"><g class="mark-group
role-frame root" role="graphics-object" aria-roledescription="group mark
container"><g transform="translate(160,160)"><path class="background"
aria-hidden="true" d="M0,0h320v320h-320Z"/><g><g class="mark-rule role-mark
radial-grid" role="graphics [...]
\ No newline at end of file
diff --git a/asciidoctor-diagrams/src/main/asciidoc/more-diagrams.adoc
b/asciidoctor-diagrams/src/main/asciidoc/more-diagrams.adoc
index effcf0c..79cf159 100644
--- a/asciidoctor-diagrams/src/main/asciidoc/more-diagrams.adoc
+++ b/asciidoctor-diagrams/src/main/asciidoc/more-diagrams.adoc
@@ -15,4 +15,193 @@ Bop --> Aliss: Yo Aliss what's up?
Aliss -> Bop: TBH, TVB
Aliss <-- Bop: Ok, good on you!
+....
+
+[vega,vega-example]
+....
+{
+ "$schema": "https://vega.github.io/schema/vega/v5.json";,
+ "description": "A radar chart example, showing multiple dimensions in a
radial layout.",
+ "width": 400,
+ "height": 400,
+ "padding": 40,
+ "autosize": {"type": "none", "contains": "padding"},
+
+ "signals": [
+ {"name": "radius", "update": "width / 2"}
+ ],
+
+ "data": [
+ {
+ "name": "table",
+ "values": [
+ {"key": "key-0", "value": 19, "category": 0},
+ {"key": "key-1", "value": 22, "category": 0},
+ {"key": "key-2", "value": 14, "category": 0},
+ {"key": "key-3", "value": 38, "category": 0},
+ {"key": "key-4", "value": 23, "category": 0},
+ {"key": "key-5", "value": 5, "category": 0},
+ {"key": "key-6", "value": 27, "category": 0},
+ {"key": "key-0", "value": 13, "category": 1},
+ {"key": "key-1", "value": 12, "category": 1},
+ {"key": "key-2", "value": 42, "category": 1},
+ {"key": "key-3", "value": 13, "category": 1},
+ {"key": "key-4", "value": 6, "category": 1},
+ {"key": "key-5", "value": 15, "category": 1},
+ {"key": "key-6", "value": 8, "category": 1}
+ ]
+ },
+ {
+ "name": "keys",
+ "source": "table",
+ "transform": [
+ {
+ "type": "aggregate",
+ "groupby": ["key"]
+ }
+ ]
+ }
+ ],
+
+ "scales": [
+ {
+ "name": "angular",
+ "type": "point",
+ "range": {"signal": "[-PI, PI]"},
+ "padding": 0.5,
+ "domain": {"data": "table", "field": "key"}
+ },
+ {
+ "name": "radial",
+ "type": "linear",
+ "range": {"signal": "[0, radius]"},
+ "zero": true,
+ "nice": false,
+ "domain": {"data": "table", "field": "value"},
+ "domainMin": 0
+ },
+ {
+ "name": "color",
+ "type": "ordinal",
+ "domain": {"data": "table", "field": "category"},
+ "range": {"scheme": "category10"}
+ }
+ ],
+
+ "encode": {
+ "enter": {
+ "x": {"signal": "radius"},
+ "y": {"signal": "radius"}
+ }
+ },
+
+ "marks": [
+ {
+ "type": "group",
+ "name": "categories",
+ "zindex": 1,
+ "from": {
+ "facet": {"data": "table", "name": "facet", "groupby": ["category"]}
+ },
+ "marks": [
+ {
+ "type": "line",
+ "name": "category-line",
+ "from": {"data": "facet"},
+ "encode": {
+ "enter": {
+ "interpolate": {"value": "linear-closed"},
+ "x": {"signal": "scale('radial', datum.value) *
cos(scale('angular', datum.key))"},
+ "y": {"signal": "scale('radial', datum.value) *
sin(scale('angular', datum.key))"},
+ "stroke": {"scale": "color", "field": "category"},
+ "strokeWidth": {"value": 1},
+ "fill": {"scale": "color", "field": "category"},
+ "fillOpacity": {"value": 0.1}
+ }
+ }
+ },
+ {
+ "type": "text",
+ "name": "value-text",
+ "from": {"data": "category-line"},
+ "encode": {
+ "enter": {
+ "x": {"signal": "datum.x"},
+ "y": {"signal": "datum.y"},
+ "text": {"signal": "datum.datum.value"},
+ "align": {"value": "center"},
+ "baseline": {"value": "middle"},
+ "fill": {"value": "black"}
+ }
+ }
+ }
+ ]
+ },
+ {
+ "type": "rule",
+ "name": "radial-grid",
+ "from": {"data": "keys"},
+ "zindex": 0,
+ "encode": {
+ "enter": {
+ "x": {"value": 0},
+ "y": {"value": 0},
+ "x2": {"signal": "radius * cos(scale('angular', datum.key))"},
+ "y2": {"signal": "radius * sin(scale('angular', datum.key))"},
+ "stroke": {"value": "lightgray"},
+ "strokeWidth": {"value": 1}
+ }
+ }
+ },
+ {
+ "type": "text",
+ "name": "key-label",
+ "from": {"data": "keys"},
+ "zindex": 1,
+ "encode": {
+ "enter": {
+ "x": {"signal": "(radius + 5) * cos(scale('angular', datum.key))"},
+ "y": {"signal": "(radius + 5) * sin(scale('angular', datum.key))"},
+ "text": {"field": "key"},
+ "align": [
+ {
+ "test": "abs(scale('angular', datum.key)) > PI / 2",
+ "value": "right"
+ },
+ {
+ "value": "left"
+ }
+ ],
+ "baseline": [
+ {
+ "test": "scale('angular', datum.key) > 0", "value": "top"
+ },
+ {
+ "test": "scale('angular', datum.key) == 0", "value": "middle"
+ },
+ {
+ "value": "bottom"
+ }
+ ],
+ "fill": {"value": "black"},
+ "fontWeight": {"value": "bold"}
+ }
+ }
+ },
+ {
+ "type": "line",
+ "name": "outer-line",
+ "from": {"data": "radial-grid"},
+ "encode": {
+ "enter": {
+ "interpolate": {"value": "linear-closed"},
+ "x": {"field": "x2"},
+ "y": {"field": "y2"},
+ "stroke": {"value": "lightgray"},
+ "strokeWidth": {"value": 1}
+ }
+ }
+ }
+ ]
+}
....
\ No newline at end of file
