sim/scripts

Block Documentation Generator

This directory contains scripts to automatically generate documentation for all blocks in the Sim 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 apps/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:

# 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:

./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:

{/_ 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:

{/_ 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.