support doc overrides for inputs & fields

src/definitions/block_definition.js

@@ -18,6 +18,7 @@ class BlockDefinition {
   name = null
 
   description = ''
+  docOverrides = {}
   ioPlus = false
 
   colour = null
@@ -178,6 +179,7 @@ BlockDefinition.parseRawDefinition = function(rawBlockDefinition, definitionPath
   blockDef.type = rawBlockDefinition.type
   blockDef.name = rawBlockDefinition.name
   blockDef.primaryCategory = rawBlockDefinition.primaryCategory
+  blockDef.docOverrides = rawBlockDefinition.docOverrides
   blockDef.description = rawBlockDefinition.description
     ? niceTemplate(rawBlockDefinition.description)
     : ""

src/docs/render_block_fields.js

@@ -1,10 +1,14 @@
-import { capitalize, map, mapValues, values } from 'lodash-es'
+import { capitalize, keys, map, mapValues, pickBy, values } from 'lodash-es'
 
 import { niceTemplate } from '#src/util.js'
 
 
 const
   renderFields = definition => {
+    if(definition.docOverrides?.fields) {
+      return renderOverridenFields(definition)
+    }
+
     const fields = values(mapValues(definition.fields, (newField, name) => {
       newField.field = name
       return newField
@@ -15,6 +19,22 @@ const
     return fields.map(renderField).join("\n\n")
   },
 
+  renderOverridenFields = definition => {
+    // warn if any inputs have descriptions that won't be rendered
+    const
+      { fields } = definition.docOverrides,
+      missedFields = keys(pickBy(definition.fields, "description")).join(", ")
+
+    if(missedFields) {
+      console.warn(`Warning [${definition.type}]: Inputs doc is overriden, input descriptions will not be seen for: ${missedFields}`)
+    }
+
+    // determine if the override is a function to call
+    return niceTemplate(typeof fields === 'string'
+      ? fields
+      : fields(definition))
+  },
+
   renderField = field => {
     const lines = []
 

src/docs/render_block_inputs.js

@@ -1,12 +1,38 @@
-import { capitalize, forEach, keys } from 'lodash-es'
+import { capitalize, pickBy, forEach, keys } from 'lodash-es'
+
+import { niceTemplate } from '#src/util.js'
 
 
 const
   renderInputs = definition => {
+    if(definition.docOverrides?.inputs) {
+      return renderOverridenInputs(definition)
+    }
+
     if(!keys(definition.inputs).length) {
       return "This block has no inputs"
     }
 
+    return renderEachInput(definition)
+  },
+
+  renderOverridenInputs = definition => {
+    // warn if any inputs have descriptions that won't be rendered
+    const
+      { inputs } = definition.docOverrides,
+      missedInputs = keys(pickBy(definition.inputs, "description")).join(", ")
+
+    if(missedInputs) {
+      console.warn(`Warning [${definition.type}]: Inputs doc is overriden, input descriptions will not be seen for: ${missedInputs}`)
+    }
+
+    // determine if the override is a function to call
+    return niceTemplate(typeof inputs === 'string'
+      ? inputs
+      : inputs(definition))
+  },
+
+  renderEachInput = definition => {
     const lines = []
     forEach(definition.inputs, (input, inputName) => {
       if(input.type === 'label') { return }