WIP bring block collaborators into doc workspace

app/blocks/math/round.js

@@ -3,6 +3,15 @@ export default {
   bytecodeKey: "round",
   name: "Round/Floor/Ceiling",
   description: "Round a value to the nearest whole number via round, floor, or ceiling functions",
+  docBlocks: [
+    {
+      type: 'io_math_number',
+      fields: { NUM: 1.45 }
+    }, {
+      type: 'io_text',
+      fields: { TEXT: "1.55" }
+    }
+  ],
   color: 120,
 
   connections: {

docs/components/blockly_workspace.vue

@@ -4,23 +4,28 @@
   import initialWorkspace from "../blockly/workspace.json"
 
   const
-    { block, width="100%", height="200px", toolbox=true } = defineProps(
-      ['block', 'width', 'height', 'toolbox']
+    { block, blocks=[], width="100%", height="200px", toolbox=true } = defineProps(
+      ['block', 'blocks', 'width', 'height', 'toolbox']
     ),
     injectOptions = {},
     options = {
       injectOptions,
       workspaceJson: block
         ? {
-            "blocks": {
-              "languageVersion": 0,
-              "blocks": [
+            blocks: {
+              languageVersion: 0,
+              blocks: [
                 {
-                  "type": block,
-                  "deletable": false,
-                  "x": 50,
-                  "y": 50
-                }
+                  type: block,
+                  deletable: false,
+                  x: 50,
+                  y: 50
+                },
+                ...blocks.map((docBlock, idx) => ({
+                  ...docBlock,
+                  x: 150,
+                  y: idx*30 + 50
+                }))
               ]
             }
           }

src/block_definition.js

@@ -16,6 +16,7 @@ class BlockDefinition {
   name = null
 
   description = ''
+  docBlocks = null
 
   colour = null
   color = null
@@ -80,6 +81,7 @@ BlockDefinition.parseRawDefinition = function(rawBlockDefinition, definitionPath
   blockDef.description = rawBlockDefinition.description
     ? niceTemplate(rawBlockDefinition.description)
     : ""
+  blockDef.docBlocks = rawBlockDefinition.docBlocks
   blockDef.tooltip = blockDef.description.split("\n")[0]
   blockDef.disabled = !!rawBlockDefinition.disabled
   blockDef.visualization = rawBlockDefinition.visualization

src/docs/render_block.js

@@ -5,18 +5,16 @@ import renderInputs from './render_block_inputs.js'
 
 
 const
-  renderDescription = definition => {
-    const
-      rawDescription = definition.visualization?.tooltip,
-      description = rawDescription
-        ? rawDescription.replaceAll("\n", "\n    ")
-        : "No docs for this block, yet."
-
-    return `    ${ description }`
-  },
+  renderDescription = ({ description }) => description || "No docs for this block, yet.",
 
   renderWorkspace = definition => {
-    return `<BlocklyWorkspace :toolbox="false" block="${ definition.type }" />`
+    const workspaceProps = JSON.stringify({
+      toolbox: false,
+      block: definition.type,
+      blocks: definition.docBlocks || []
+    })
+
+    return `<BlocklyWorkspace v-bind='${ workspaceProps }' />`
   },
 
   renderOutput = definition => {
@@ -35,7 +33,8 @@ editLink: true
 
 # Block: ${definition.name}
 
-## Description
+Type: \`${definition.type}\`
+
 ${ renderDescription(definition) }
 
 ## Workspace

src/docs/render_block_fields.js

@@ -26,7 +26,7 @@ const
     lines.push(`### \`${capitalize(field.field)}\`:`)
 
     // add lines based on what properties are present
-    Object.hasOwn(field, 'description') && lines.push(niceTemplate(field.description).replaceAll("\n", "\n\n"))
+    Object.hasOwn(field, 'description') && lines.push(niceTemplate(field.description))
     Object.hasOwn(field, 'text') && lines.push(renderTextField(field))
     Object.hasOwn(field, 'checked') && lines.push(renderCheckboxField(field))
     Object.hasOwn(field, 'options') && lines.push(renderSelectField(field))

src/importer/block_importer.js

@@ -48,6 +48,7 @@ const
     "fields",
     "template",
     "description",
+    "docBlocks",
     "disabled",
     "generators",
     "regenerators",

src/util.js

@@ -16,5 +16,7 @@ export const
       return map(remainingLines, line => line.slice(indentCounts[0])).join("\n")
     }
 
+    // TODO: support niceties for markdown, double-newlines, escaping, etc
+
     return tplString
   }