feat(docs): added script to auto-generate docs for integrations/tools (#293)

* added scaffolding for auto-generating docs for integrations based on block definition, get rendering error for mdx pages

* page renders, have to add more useful information

* standardized tool naming convention, added script to autogenerate docs for integrations, added docs for each tool

* re-generated docs, updated CONTRIBUTING.md to reflect new format

* added a dedicated tools page

* added additional information for tools, added manual section logic to docs producer

* added a link back to sim studio, fixed z level issue on mobile, added better intro

* updated script to more accurately reflect the params for each tool, as well as the overall blocks' output

scripts/README.md

@@ -0,0 +1,109 @@
+# Block Documentation Generator
+
+This directory contains scripts to automatically generate documentation for all blocks in the Sim Studio platform.
+
+## Available Scripts
+
+- `generate-docs.sh`: Generates documentation for all blocks
+- `setup-doc-generator.sh`: Installs dependencies required for the documentation generator
+
+## How It Works
+
+The documentation generator:
+
+1. Scans the `sim/blocks/blocks/` directory for all block definition files
+2. Extracts metadata from each block including:
+   - Name, description, and category
+   - Input and output specifications
+   - Configuration parameters
+3. Generates standardized Markdown documentation for each block
+4. Updates the navigation metadata in `meta.json`
+
+## Running the Generator
+
+To generate documentation manually:
+
+```bash
+# From the project root
+./scripts/generate-docs.sh
+```
+
+## Troubleshooting TypeScript Errors
+
+If you encounter TypeScript errors when running the documentation generator, run the setup script to install the necessary dependencies:
+
+```bash
+./scripts/setup-doc-generator.sh
+```
+
+This will:
+1. Install TypeScript, ts-node, and necessary type definitions
+2. Create a proper tsconfig.json for the scripts directory
+3. Configure the scripts directory to use ES modules
+
+### Common Issues
+
+1. **Missing Type Declarations**: Run the setup script to install @types/node and @types/react
+2. **JSX Errors in block-info-card.tsx**: These don't affect functionality and can be ignored if you've run the setup script
+3. **Module Resolution**: The setup script configures proper ES module support
+
+## CI Integration
+
+The documentation generator runs automatically as part of the CI/CD pipeline whenever changes are pushed to the main branch. The updated documentation is committed back to the repository.
+
+## Adding Support for New Block Properties
+
+If you add new properties to block definitions that should be included in the documentation, update the `generateMarkdownForBlock` function in `scripts/generate-block-docs.ts`. 
+
+## Preserving Manual Content
+
+The documentation generator now supports preserving manually added content when regenerating docs. This allows you to enhance the auto-generated documentation with custom examples, additional context, or any other content without losing your changes when the docs are regenerated.
+
+### How It Works
+
+1. The generator creates clean documentation without any placeholders or markers
+2. If you add manual content to a file using special comment markers, that content will be preserved during regeneration
+3. The manual content is intelligently inserted at the appropriate section when docs are regenerated
+
+### Using Manual Content Markers
+
+To add custom content to any tool's documentation, insert MDX comment blocks with section markers:
+
+```markdown
+{/* MANUAL-CONTENT-START:sectionName */}
+Your custom content here (Markdown formatting supported)
+{/* MANUAL-CONTENT-END */}
+```
+
+Replace `sectionName` with one of the supported section names:
+
+- `intro` - Content at the top of the document after the BlockInfoCard
+- `usage` - Additional usage instructions and examples
+- `configuration` - Custom configuration details
+- `outputs` - Additional output information or examples
+- `notes` - Extra notes at the end of the document
+
+### Example
+
+To add custom examples to a tool doc:
+
+```markdown
+{/* MANUAL-CONTENT-START:usage */}
+## Examples
+
+### Basic Usage
+
+```json
+{
+  "parameter": "value",
+  "anotherParameter": "anotherValue"
+}
+```
+
+### Advanced Configuration
+
+Here's how to use this tool for a specific use case...
+{/* MANUAL-CONTENT-END */}
+```
+
+When the documentation is regenerated, your manual content will be preserved in the appropriate section automatically. The script will not add any placeholders or markers to files by default. 

scripts/generate-docs.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+# Set error handling
+set -e
+
+# Enable debug mode if DEBUG env var is set
+if [ ! -z "$DEBUG" ]; then
+  set -x
+  echo "Debug mode enabled"
+fi
+
+# Get script directories
+SCRIPTS_DIR=$(dirname "$0")
+ROOT_DIR=$(cd "$SCRIPTS_DIR/.." && pwd)
+echo "Scripts directory: $SCRIPTS_DIR"
+echo "Root directory: $ROOT_DIR"
+
+# Check if dependencies are installed in scripts directory
+if [ ! -d "$SCRIPTS_DIR/node_modules" ]; then
+  echo "Required dependencies not found. Installing now..."
+  bash "$SCRIPTS_DIR/setup-doc-generator.sh"
+fi
+
+# Generate documentation
+echo "Generating block documentation..."
+
+# Check if necessary files exist
+if [ ! -f "$SCRIPTS_DIR/generate-block-docs.ts" ]; then
+  echo "Error: Could not find generate-block-docs.ts script"
+  ls -la "$SCRIPTS_DIR"
+  exit 1
+fi
+
+if [ ! -f "$SCRIPTS_DIR/tsconfig.json" ]; then
+  echo "Error: Could not find tsconfig.json in scripts directory"
+  exit 1
+fi
+
+# Check if npx is available
+if ! command -v npx &> /dev/null; then
+  echo "Error: npx is not installed. Please install Node.js first."
+  exit 1
+fi
+
+# Change to scripts directory to use local dependencies
+cd "$SCRIPTS_DIR"
+echo "Executing: npx tsx ./generate-block-docs.ts"
+
+# Run the generator with tsx using local dependencies
+if ! npx tsx ./generate-block-docs.ts; then
+  echo ""
+  echo "Error running documentation generator."
+  echo ""
+  echo "For more detailed debugging, run with DEBUG=1:"
+  echo "DEBUG=1 ./scripts/generate-docs.sh"
+  exit 1
+fi
+
+echo "Documentation generation complete!"
+echo "Generated documentation can be found in docs/content/docs/tools/" 

scripts/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "sim-doc-generator",
+  "version": "1.0.0",
+  "description": "Documentation generator for Sim Studio blocks",
+  "type": "module",
+  "private": true,
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "@types/react": "^19.1.2",
+    "glob": "^11.0.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}

scripts/setup-doc-generator.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# Get the scripts directory path
+SCRIPTS_DIR=$(dirname "$0")
+cd "$SCRIPTS_DIR"
+echo "Working in scripts directory: $(pwd)"
+
+echo "Setting up documentation generator..."
+
+# Create package.json for scripts directory
+cat > package.json << EOF
+{
+  "name": "sim-doc-generator",
+  "version": "1.0.0",
+  "description": "Documentation generator for Sim Studio blocks",
+  "type": "module",
+  "private": true
+}
+EOF
+
+# Install dependencies local to scripts directory
+npm install --save-dev typescript @types/node @types/react ts-node tsx glob
+
+# Setup tsconfig.json
+cat > tsconfig.json << EOF
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  },
+  "include": ["./**/*.ts"]
+}
+EOF
+
+echo "Dependencies installed successfully!"
+echo "You can now run './scripts/generate-docs.sh' to generate the documentation." 

scripts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  },
+  "include": ["./**/*.ts"]
+}