Merge pull request #36 from adafruit/use-md-files

Add raw markdown option for block docs

Author: lorennorman

README.md

@@ -32,6 +32,28 @@ Now 2 processes should be running:
 
 When you're done working simply press `CTRL + C` to terminate the processes.
 
+### Generating Blocks and Docs
+
+To generate a new block file:
+```sh
+npm run generate:block path/block_type # generates block named "Block Type" at app/blocks/path/block_type.js
+```
+
+To generate a complete markdown document for a block:
+```sh
+npm run generate:block:doc path/block_type # generates app/blocks/path/block_type.md
+```
+The above will generate an entire block documentation page using the embedded documenation in the `block_type.js` file, if present. The documentation exporter will ignore the block definition and use this file instead.
+
+You can also export certain sections of documentation:
+```sh
+npm run generate:block:doc path/block_type description # generates app/blocks/path/block_type.description.md
+npm run generate:block:doc path/block_type inputs # generates app/blocks/path/block_type.inputs.md
+npm run generate:block:doc path/block_type fields # generates app/blocks/path/block_type.fields.md
+```
+
+These files are markdown fragments, generated from embedded docs in `block_type.js`, that will be used only for their particular sections.
+
 ### Exporting
 
 Export a Blockly application:

app/blocks/text/compare.description.md

@@ -0,0 +1,160 @@
+Compare two text values using different comparison operations. Perfect for conditional logic, filtering data, validating user input, or creating smart automation rules based on text content matching, differences, or substring detection.
+
+## What is Text Compare?
+
+The Text Compare block evaluates two text inputs using a specified comparison operator and returns true or false. This enables you to build conditional logic based on text content, whether checking for exact matches, detecting differences, or finding substrings within larger text.
+
+## How It Works
+
+The block performs three types of text comparison operations:
+- **Equals (=)** - Exact match comparison (case-sensitive)
+- **Not Equals (≠)** - Different text detection
+- **Includes** - Substring detection within text
+
+## Comparison Operators
+
+### Equals (=) - Exact Match
+Returns true when both text values are exactly the same, including case sensitivity.
+
+::: warning Case Sensitivity Alert
+Text comparison is case-sensitive! "Hello" is NOT equal to "hello"
+:::
+
+**Examples:**
+- "hello" = "hello" → **true**
+- "Hello" = "hello" → **false** (case-sensitive)
+- "test123" = "test123" → **true**
+- "  test  " = "test" → **false** (whitespace matters)
+
+**Common Uses:**
+- ✅ Check device status: `device_status = "online"`
+- ✅ Validate user role: `user_role = "admin"`
+- ✅ Confirm completion: `task_status = "completed"`
+
+### Not Equals (≠) - Different Values
+Returns true when text values are different in any way.
+
+**Examples:**
+- "hello" ≠ "world" → **true**
+- "same" ≠ "same" → **false**
+- "Test" ≠ "test" → **true** (case-sensitive)
+
+**Common Uses:**
+- ⚠️ Detect changes: `current_status ≠ previous_status`
+- 🚫 Block guest users: `username ≠ "guest"`
+- 📝 Validate required fields: `input_field ≠ ""`
+
+### Includes - Substring Detection
+Returns true when the left text contains the right text as a substring.
+
+::: tip Perfect for Keyword Searching
+Use includes to search for keywords within longer text like error messages, logs, or user input
+:::
+
+**Examples:**
+- "hello world" includes "world" → **true**
+- "temperature alert" includes "temp" → **true**
+- "test" includes "testing" → **false** (left must contain right)
+
+**Common Uses:**
+- 🔍 Find errors: `error_log includes "timeout"`
+- 📧 Email filtering: `email_address includes "@company.com"`
+- 🎯 Command parsing: `voice_command includes "lights"`
+
+## Practical Examples
+
+::: details 🏠 Smart Home Examples
+
+### Door & Security
+~~~javascript
+// Check if door is locked
+door_status = "locked" → Turn off porch light
+
+// Alert if door left open
+door_status ≠ "closed" → Send notification
+
+// Security monitoring
+security_log includes "breach" → Trigger alarm
+~~~
+
+### Temperature & Climate
+~~~javascript
+// AC control
+room_temp = "hot" → Turn on air conditioning
+
+// Sensor errors
+temp_reading includes "error" → Send maintenance alert
+
+// Room occupancy
+bedroom_status ≠ "occupied" → Reduce heating
+~~~
+
+:::
+
+::: details 🔧 System Monitoring Examples
+
+### Error Detection
+~~~javascript
+// System health
+system_status ≠ "healthy" → Send alert
+error_message includes "critical" → Immediate notification
+
+// Performance monitoring
+response_time includes "slow" → Log performance issue
+~~~
+
+### Device Management
+~~~javascript
+// Connectivity checks
+device_ping ≠ "success" → Mark device offline
+connection_type = "ethernet" → Use high-speed settings
+
+// Battery monitoring
+battery_level includes "low" → Send low battery warning
+~~~
+
+:::
+
+## Common Issues & Solutions
+
+::: details 🔤 Case Sensitivity Problems
+
+::: danger Most Common Issue
+"Online" ≠ "online" - Case matters in all comparisons!
+:::
+
+::: details ⚠️ Whitespace Issues
+
+**Hidden spaces cause comparison failures:**
+
+| What You See | Actual Value | Result |
+|--------------|--------------|--------|
+| "active" | "active " | Won't match "active" |
+| "online" | " online" | Won't match "online" |
+
+**Solutions:**
+- Be aware extra spaces break matches
+- Check for leading/trailing spaces in your data
+- Clean data at the source when possible
+
+:::
+
+::: details 🔢 Text vs Numbers
+
+::: warning Important
+This block compares TEXT, not numbers! "10" vs "9" gives unexpected results
+:::
+
+## Quick Reference
+
+### When to Use Each Operator
+| Operator | Use When | Example |
+|----------|----------|---------|
+| **Equals (=)** | Need exact match | `status = "online"` |
+| **Not Equals (≠)** | Need to detect difference | `role ≠ "guest"` |
+| **Includes** | Search within text | `message includes "error"` |
+
+### Related Blocks
+- **Number Compare** - For numeric comparisons (>, <, >=, <=)
+- **Logic AND/OR** - Combine multiple text comparisons
+- **IF/Then** - Use comparison results to control flow

app/blocks/text/compare.js

@@ -2,28 +2,32 @@
 export default {
   type: 'text_compare',
   bytecodeKey: 'textCompare',
-  name: "Compare Text",
+  name: "Text Compare",
+
   colour: 180,
   inputsInline: true,
   primaryCategory: "Logic",
-  description: "Compare any two pieces of text or data to build conditional logic in your Actions. Perfect for creating if/then statements like 'if device status equals online', 'if user name is not guest', or 'if error message contains timeout'. Works with feed values, variables, user input, or any text-based data.",
+
   connections: {
     mode: "value",
     output: "expression",
   },
-  template: `%A %OP %B`,
+
+  template: "%A %OP %B",
+
   inputs: {
     A: {
-      description: "The first value to compare (left side). Can be feed data, variable content, user input, or any text. Numbers and other data types will be automatically converted to text for comparison.",
+      description: "Left text value to compare",
       check: "expression",
-      shadow: 'io_text'
+      shadow: "io_text"
     },
     B: {
-      description: "The second value to compare (right side). Can be literal text like 'online', variable content, feed values, or any data you want to compare against the first input. Also automatically converted to text.",
+      description: "Right text value to compare",
       check: "expression",
-      shadow: 'io_text'
-    },
+      shadow: "io_text"
+    }
   },
+
   fields: {
     OP: {
       description: "Choose how to compare the two text inputs:",
@@ -34,6 +38,7 @@ export default {
       ]
     }
   },
+
   generators: {
     json: (block, generator) => {
       const
@@ -50,6 +55,7 @@ export default {
       return [ blockPayload, 0 ]
     }
   },
+
   regenerators: {
     json: (blockObject, helpers) => {
       const