Add symbolator (#1566)

Co-authored-by: Guillaume Grossetie <[email protected]>
yuzutech · Jul 14, 2023 · 482f7dc · 482f7dc
1 parent 5445d15
commit 482f7dc
Show file tree

Hide file tree

Showing 20 changed files with 342 additions and 68 deletions.
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
@@ -2,7 +2,7 @@
 
 Convert plain text diagrams to images !
 
-Kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, UMLet, Vega, Vega-Lite, WaveDrom... and more to come!
+Kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom... and more to come!
 
 ## Getting Started
 

diff --git a/README.adoc b/README.adoc
@@ -8,7 +8,7 @@ image:https://github.com/yuzutech/kroki/workflows/CI/badge.svg?branch=master[Git
 image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Zulip chat, link=https://kroki.zulipchat.com/]
 endif::[]
 
-{uri-kroki}[Kroki] provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, UMLet, Vega, Vega-Lite, WaveDrom and WireViz... and more to come!
+{uri-kroki}[Kroki] provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, SvgBob, Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz... and more to come!
 
 == Quickstart
 

diff --git a/blockdiag/examples.py b/blockdiag/examples.py
@@ -393,6 +393,28 @@ def sample(service, source):
 
 sample('ditaa', ditaa)
 
+# Symbolator
+section('Symbolator')
+symbolator = """
+module demo_device #(
+    //# {{}}
+    parameter SIZE = 8,
+    parameter RESET_ACTIVE_LEVEL = 1
+) (
+    //# {{clocks|Clocking}}
+    input wire clock,
+    //# {{control|Control signals}}
+    input wire reset,
+    input wire enable,
+    //# {{data|Data ports}}
+    input wire [SIZE-1:0] data_in,
+    output wire [SIZE-1:0] data_out
+);
+  // ...
+endmodule
+"""
+
+sample('symbolator', symbolator)
 
 section('C4 PlantUML')
 context_bigbank = """

diff --git a/ci/tasks/update-versions.js b/ci/tasks/update-versions.js
@@ -14,14 +14,14 @@ const krokiServicePath = ospath.join(rootDir, 'server', 'src', 'main', 'java', '
 
 const diagramLibraryVersions = {}
 
-function getDependencyVersion (pkg, name) {
+function getDependencyVersion(pkg, name) {
   if (name in pkg.dependencies) {
     return pkg.dependencies[name]
   }
   return pkg.devDependencies[name]
 }
 
-async function updateServiceGetVersion (javaServiceFileName, version) {
+async function updateServiceGetVersion(javaServiceFileName, version) {
   const servicePath = ospath.join(krokiServicePath, javaServiceFileName)
   const javaContent = await fs.readFile(servicePath, 'utf8')
   const versionFound = javaContent.match(/(?<= +public String getVersion\(\) {\n\s+return ")(?<version>[0-9.]+)(?=";\n\s+})/)
@@ -34,7 +34,7 @@ async function updateServiceGetVersion (javaServiceFileName, version) {
   }
 }
 
-async function updateVegaServiceGetVersion (vegaVersion, vegaLiteVersion) {
+async function updateVegaServiceGetVersion(vegaVersion, vegaLiteVersion) {
   // update vega version
   const servicePath = ospath.join(krokiServicePath, 'Vega.java')
   let javaContent = await fs.readFile(servicePath, 'utf8')
@@ -56,7 +56,7 @@ async function updateVegaServiceGetVersion (vegaVersion, vegaLiteVersion) {
   await fs.writeFile(servicePath, javaContent, 'utf8')
 }
 
-async function mvnEvaluateExpression (expression, pomRootRelativePath) {
+async function mvnEvaluateExpression(expression, pomRootRelativePath) {
   if (pomRootRelativePath === undefined) {
     pomRootRelativePath = ospath.join('server', 'pom.xml')
   }
@@ -83,7 +83,7 @@ async function mvnEvaluateExpression (expression, pomRootRelativePath) {
   })
 }
 
-function addDiagramLibraryPackageVersion (diagramName, dependencyName, directoryName) {
+function addDiagramLibraryPackageVersion(diagramName, dependencyName, directoryName) {
   if (directoryName === undefined) {
     directoryName = diagramName
   }
@@ -118,6 +118,7 @@ const diagramLibraryNames = [
   'seqdiag',
   'structurizr',
   'svgbob',
+  'symbolator',
   'umlet',
   'vega',
   'vegalite',
@@ -187,6 +188,12 @@ try {
       const { version } = pikchrVersionFound.groups
       diagramLibraryVersions.pikchr = version.slice(0, 10)
     }
+
+    const symbolatorVersionFound = line.match(/^ARG SYMBOLATOR_VERSION=(?<version>.+)$/)
+    if (symbolatorVersionFound) {
+      const { version } = symbolatorVersionFound.groups
+      diagramLibraryVersions.symbolator = version
+    }
     const umletVersionFound = line.match(/^ARG UMLET_VERSION="(?<version>.+)"$/)
     if (umletVersionFound) {
       const { version } = umletVersionFound.groups
@@ -234,7 +241,7 @@ try {
   for (let line of antoraComponentContent.split('\n')) {
     const found = line.match(/^\s+(?<name>[a-z0-9]+)-version: '?(?<version>[^']+)'?$/)
     if (found) {
-      const { name, version : versionFound } = found.groups
+      const { name, version: versionFound } = found.groups
       const version = diagramLibraryVersions[name]
       if (versionFound !== version) {
         line = line.replace(/(?<=^\s+(?<name>[a-z0-9]+)-version: '?)(?<version>[^']+)/, version)
@@ -258,6 +265,7 @@ try {
   await updateServiceGetVersion('Plantuml.java', diagramLibraryVersions.plantuml)
   await updateServiceGetVersion('Structurizr.java', diagramLibraryVersions.structurizr)
   await updateServiceGetVersion('Svgbob.java', diagramLibraryVersions.svgbob)
+  await updateServiceGetVersion('Symbolator.java', diagramLibraryVersions.symbolator)
   await updateServiceGetVersion('Umlet.java', diagramLibraryVersions.umlet)
   await updateServiceGetVersion('Wavedrom.java', diagramLibraryVersions.wavedrom)
   await updateServiceGetVersion('Wireviz.java', diagramLibraryVersions.wireviz)

diff --git a/ci/tests/diagrams/component.sv b/ci/tests/diagrams/component.sv
@@ -0,0 +1,16 @@
+module demo_device #(
+    //# {{}}
+    parameter SIZE = 8,
+    parameter RESET_ACTIVE_LEVEL = 1
+) (
+    //# {{clocks|Clocking}}
+    input wire clock,
+    //# {{control|Control signals}}
+    input wire reset,
+    input wire enable,
+    //# {{data|Data ports}}
+    input wire [SIZE-1:0] data_in,
+    output wire [SIZE-1:0] data_out
+);
+  // ...
+endmodule
diff --git a/ci/tests/smoke.js b/ci/tests/smoke.js
@@ -5,41 +5,42 @@ import * as url from 'url'
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
 
 const tests = [
-  {engine: 'graphviz', file: 'hello.dot', options: {}, outputFormat: ['svg', 'jpeg']},
-  {engine: 'dot', file: 'hello.dot', options: {}, outputFormat: ['svg', 'jpeg']},
-  {engine: 'blockdiag', file: 'kroki.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'seqdiag', file: 'sequence.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'actdiag', file: 'actions.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'nwdiag', file: 'network.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'c4plantuml', file: 'banking-system.puml', options: {}, outputFormat: ['svg', 'pdf', 'png', 'txt']},
-  {engine: 'dbml', file: 'dbml.dbml', options: {}, outputFormat: ['svg']},
-  {engine: 'ditaa', file: 'components.ditaa', options: {}, outputFormat: ['svg']},
-  {engine: 'erd', file: 'schema.erd', options: {}, outputFormat: ['svg']},
-  {engine: 'mermaid', file: 'contribute.mmd', options: {}, outputFormat: ['svg']},
-  {engine: 'bpmn', file: 'example.bpmn', options: {}, outputFormat: ['svg']},
-  {engine: 'plantuml', file: 'architecture.puml', options: {}, outputFormat: ['svg', 'pdf', 'png', 'txt']},
-  {engine: 'svgbob', file: 'cloud.bob', options: {}, outputFormat: ['svg']},
-  {engine: 'nomnoml', file: 'pirate.nomnoml', options: {}, outputFormat: ['svg']},
-  {engine: 'packetdiag', file: 'packet.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'rackdiag', file: 'rack.diag', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'vega', file: 'bar-chart.vega', options: {}, outputFormat: ['svg', 'png', 'pdf']},
-  {engine: 'vegalite', file: 'discretizing-scale.vlite', options: {}, outputFormat: ['svg', 'png', 'pdf']},
-  {engine: 'wavedrom', file: 'wavedrom.json5', options: {}, outputFormat: ['svg']},
-  {engine: 'wavedrom', file: 'bitfield.json5', options: {}, outputFormat: ['svg']},
-  {engine: 'bytefield', file: 'bytefield.bf', options: {}, outputFormat: ['svg']},
-  {engine: 'umlet', file: 'umlet.xml', options: {}, outputFormat: ['svg']},
-  {engine: 'excalidraw', file: 'venn.excalidraw', options: {}, outputFormat: ['svg']},
-  {engine: 'pikchr', file: 'sqlite-architecture.pikchr', options: {}, outputFormat: ['svg']},
-  {engine: 'structurizr', file: 'gettingstarted.structurizr', options: {}, outputFormat: ['svg']},
-  {engine: 'diagramsnet', file: 'diagramsnet-infography.xml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'diagramsnet', file: 'diagramsnet-mindmap.xml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'diagramsnet', file: 'diagramsnet-network.xml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'diagramsnet', file: 'diagramsnet-ui.xml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'diagramsnet', file: 'diagramsnet-venn.xml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'd2', file: 'connections.d2', options: {}, outputFormat: ['svg']},
-  {engine: 'd2', file: 'connections.d2', options: {sketch: 'true'}, outputFormat: ['svg']},
-  {engine: 'wireviz', file: 'wireviz.yaml', options: {}, outputFormat: ['svg', 'png']},
-  {engine: 'tikz', file: 'periodic-table.tex', options: {}, outputFormat: ['jpeg', 'pdf', 'png', 'svg']}
+  { engine: 'graphviz', file: 'hello.dot', options: {}, outputFormat: ['svg', 'jpeg'] },
+  { engine: 'dot', file: 'hello.dot', options: {}, outputFormat: ['svg', 'jpeg'] },
+  { engine: 'blockdiag', file: 'kroki.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'seqdiag', file: 'sequence.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'actdiag', file: 'actions.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'nwdiag', file: 'network.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'c4plantuml', file: 'banking-system.puml', options: {}, outputFormat: ['svg', 'pdf', 'png', 'txt'] },
+  { engine: 'dbml', file: 'dbml.dbml', options: {}, outputFormat: ['svg'] },
+  { engine: 'ditaa', file: 'components.ditaa', options: {}, outputFormat: ['svg'] },
+  { engine: 'symbolator', file: 'component.sv', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'erd', file: 'schema.erd', options: {}, outputFormat: ['svg'] },
+  { engine: 'mermaid', file: 'contribute.mmd', options: {}, outputFormat: ['svg'] },
+  { engine: 'bpmn', file: 'example.bpmn', options: {}, outputFormat: ['svg'] },
+  { engine: 'plantuml', file: 'architecture.puml', options: {}, outputFormat: ['svg', 'pdf', 'png', 'txt'] },
+  { engine: 'svgbob', file: 'cloud.bob', options: {}, outputFormat: ['svg'] },
+  { engine: 'nomnoml', file: 'pirate.nomnoml', options: {}, outputFormat: ['svg'] },
+  { engine: 'packetdiag', file: 'packet.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'rackdiag', file: 'rack.diag', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'vega', file: 'bar-chart.vega', options: {}, outputFormat: ['svg', 'png', 'pdf'] },
+  { engine: 'vegalite', file: 'discretizing-scale.vlite', options: {}, outputFormat: ['svg', 'png', 'pdf'] },
+  { engine: 'wavedrom', file: 'wavedrom.json5', options: {}, outputFormat: ['svg'] },
+  { engine: 'wavedrom', file: 'bitfield.json5', options: {}, outputFormat: ['svg'] },
+  { engine: 'bytefield', file: 'bytefield.bf', options: {}, outputFormat: ['svg'] },
+  { engine: 'umlet', file: 'umlet.xml', options: {}, outputFormat: ['svg'] },
+  { engine: 'excalidraw', file: 'venn.excalidraw', options: {}, outputFormat: ['svg'] },
+  { engine: 'pikchr', file: 'sqlite-architecture.pikchr', options: {}, outputFormat: ['svg'] },
+  { engine: 'structurizr', file: 'gettingstarted.structurizr', options: {}, outputFormat: ['svg'] },
+  { engine: 'diagramsnet', file: 'diagramsnet-infography.xml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'diagramsnet', file: 'diagramsnet-mindmap.xml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'diagramsnet', file: 'diagramsnet-network.xml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'diagramsnet', file: 'diagramsnet-ui.xml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'diagramsnet', file: 'diagramsnet-venn.xml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'd2', file: 'connections.d2', options: {}, outputFormat: ['svg'] },
+  { engine: 'd2', file: 'connections.d2', options: { sketch: 'true' }, outputFormat: ['svg'] },
+  { engine: 'wireviz', file: 'wireviz.yaml', options: {}, outputFormat: ['svg', 'png'] },
+  { engine: 'tikz', file: 'periodic-table.tex', options: {}, outputFormat: ['jpeg', 'pdf', 'png', 'svg'] }
 ]
 
 chai.use(chaiHttp)
@@ -95,7 +96,7 @@ describe('Diagrams', function () {
 describe('PlantUML native image', function () {
   this.timeout(15000)
   it('plantuml (native image) should convert class diagram (issue#1546)', async () => {
-    const testCase = {engine: 'plantuml', file: 'class.puml'}
+    const testCase = { engine: 'plantuml', file: 'class.puml' }
     const response = await sendRequest(testCase, 'svg')
     try {
       expect(response.status).to.equal(200)
@@ -109,7 +110,7 @@ describe('PlantUML native image', function () {
 describe('CJK font', function () {
   this.timeout(15000)
   it('plantuml should compute correct text length (issue#574)', async () => {
-    const testCase = {engine: 'plantuml', file: 'chinese.puml'}
+    const testCase = { engine: 'plantuml', file: 'chinese.puml' }
     const response = await sendRequest(testCase, 'svg')
     try {
       expect(response.body.toString('utf8')).to.include('textLength="56"')
@@ -119,7 +120,7 @@ describe('CJK font', function () {
     }
   })
   it('mermaid should compute correct text length (issue#1167)', async () => {
-    const testCase = {engine: 'mermaid', file: 'japanese.mermaid'}
+    const testCase = { engine: 'mermaid', file: 'japanese.mermaid' }
     const response = await sendRequest(testCase, 'svg')
     try {
       const data = response.body.toString('utf8')
@@ -137,23 +138,23 @@ describe('CJK font', function () {
 
 describe('Health', function () {
   this.timeout(15000)
-  ;['/health', '/healthz', '/v1/health'].forEach((endpoint) => {
-    it(`should return health status from ${endpoint}`, async () => {
-      const response = await chai.request('localhost:8000')
-        .get(endpoint)
-        .set('Accept', 'application/health+json')
-        .send()
+    ;['/health', '/healthz', '/v1/health'].forEach((endpoint) => {
+      it(`should return health status from ${endpoint}`, async () => {
+        const response = await chai.request('localhost:8000')
+          .get(endpoint)
+          .set('Accept', 'application/health+json')
+          .send()
 
-      try {
-        expect(response.status).to.equal(200)
-        expect(response.body.status).to.equal('pass')
-        const engines = Array.from(new Set(tests.map((it) => it.engine)))
-        engines.push('kroki')
-        expect(response.body.version).to.have.keys(engines)
-      } catch (err) {
-        console.log('response:', response.text)
-        throw err
-      }
+        try {
+          expect(response.status).to.equal(200)
+          expect(response.body.status).to.equal('pass')
+          const engines = Array.from(new Set(tests.map((it) => it.engine)))
+          engines.push('kroki')
+          expect(response.body.version).to.have.keys(engines)
+        } catch (err) {
+          console.log('response:', response.text)
+          throw err
+        }
+      })
     })
-  })
 })
diff --git a/docs/antora.yml b/docs/antora.yml
@@ -25,6 +25,7 @@ asciidoc:
     seqdiag-version: 3.0.0
     structurizr-version: 1.30.1
     svgbob-version: 0.7.0
+    symbolator-version: 1.2.2
     umlet-version: 15.1
     vega-version: 5.25.0
     vegalite-version: 5.9.3

diff --git a/docs/modules/ROOT/pages/architecture.adoc b/docs/modules/ROOT/pages/architecture.adoc
@@ -69,6 +69,10 @@ The `yuzutech/kroki` Docker image contains the following diagrams libraries out-
 |{svgbob-version}
 //|Binary `/rust/bin/svgbob`
 
+|https://hdl.github.io/symbolator/[Symbolator]
+|{symbolator-version}
+//|Binary `/usr/bin/symbolator`
+
 |https://github.com/umlet/umlet[UMlet]
 |{umlet-version}
 //|Java library

diff --git a/docs/modules/ROOT/pages/diagram-types.adoc b/docs/modules/ROOT/pages/diagram-types.adoc
@@ -38,6 +38,7 @@ Diagram::
 * Digital Timing diagram (waveform)
 * BPMN diagram
 * Bytefield diagram
+* HDL Component diagram
 * Excalidraw
 * https://www.diagrams.net/[diagrams.net] (experimental)
 * WireViz

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -5,8 +5,8 @@
 === Convert plain text diagrams to images !
 
 Kroki provides a unified HTTP API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag),
-BPMN, Bytefield, C4 (with PlantUML), Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, PlantUML, Structurizr, SvgBob, UMLet,
-Vega, Vega-Lite, WaveDrom and WireViz... and more to come!
+BPMN, Bytefield, C4 (with PlantUML), Diagrams.net (experimental), Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, PlantUML, Structurizr, SvgBob,
+Symbolator, UMLet, Vega, Vega-Lite, WaveDrom and WireViz... and more to come!
 
 Kroki is available as a Self-Managed instance. +
 We are also _actively_ looking for sponsors to provide Kroki as a free service:

diff --git a/docs/modules/setup/pages/configuration.adoc b/docs/modules/setup/pages/configuration.adoc
@@ -117,6 +117,7 @@ you can override its location manually using an environment variable or a Java s
 `KROKI_PIKCHR_BIN_PATH`:: Path to `pikchr` binary (defaults: `/usr/bin/pikchr`)
 `KROKI_PLANTUML_BIN_PATH`:: Path to `plantuml` binary (defaults: `/usr/bin/plantuml`)
 `KROKI_SVGBOB_BIN_PATH`:: Path to `svgbob` binary (defaults: `/usr/bin/svgbob`)
+`KROKI_SYMBOLATOR_BIN_PATH`:: Path to `symbolator` binary (defaults: `/usr/bin/symbolator`)
 `KROKI_TIKZ2SVG_BIN_PATH`:: Path to `tikz2svg` binary (defaults: `/usr/bin/tikz2svg`)
 `KROKI_UMLET_BIN_PATH`:: Path to `umlet` binary (defaults: `/usr/bin/umlet`)
 `KROKI_VEGA_BIN_PATH`:: Path to `vega` binary which supports both Vega and Vega-Lite grammar (defaults: `/usr/bin/bytefield`)

diff --git a/docs/modules/setup/pages/diagram-options.adoc b/docs/modules/setup/pages/diagram-options.adoc
@@ -232,3 +232,46 @@ The complete list of options is available in Mermaid source code at: https://git
 
 |===
 
+
+== Symbolator
+
+[cols="1m,1a,2a",opts="header"]
+|===
+|Name
+|Allowable Values
+|Description
+
+|component
+|_string_ +
+empty string ("")
+|Select the component that will be rendered +
+If not set, the last component will be rendered
+
+|transparent
+|_flag_ +
+empty string ("")
+|Background will be transparent instead of white +
+With flag set, option takes effect.
+
+|title
+|_string_ +
+empty string ("")
+|This title will be inserted into the diagram
+
+|scale
+|_number_ +
+*`1.0`*
+|Diagram will be scaled by this factor
+
+|no-type
+|_flag_ +
+empty string ("")
+|Omit type information for the ports
+
+|library-name
+|_string_ +
+empty string ("")
+|Add name of a library to the diagram. +
+Only works if title is also set
+
+|===