A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.13,<3.14"
# dependencies = []
#
# [tool.uv]
# exclude-newer = "2025-06-27T12:38:25.742953-04:00"
# ///
"""Generate documentation for marimo's lint rules.
This script automatically generates comprehensive documentation for all lint rules
in the marimo codebase, including:
- Main rules index page with categorized listings
- Individual rule pages with detailed explanations
- Validation of rule metadata and structure
Inspired by Ruff's documentation structure but adapted for marimo's style.
"""
from __future__ import annotations
import ast
import re
import textwrap
from dataclasses import dataclass
from enum import Enum
from pathlib import Path
from typing import Any
class Severity(Enum):
"""Severity levels for diagnostic errors."""
FORMATTING = "formatting"
RUNTIME = "runtime"
BREAKING = "breaking"
WASM = "wasm"
@dataclass
class RuleInfo:
"""Information about a lint rule extracted from source code."""
code: str
name: str
description: str
severity: Severity
fixable: bool | str
docstring: str
file_path: Path
class_name: str
# Add marimo to the path so we can import it
MARIMO_ROOT = Path(__file__).parent.parent
def extract_rule_info_from_file(file_path: Path) -> list[RuleInfo]:
"""Extract rule information from a Python file."""
content = file_path.read_text()
tree = ast.parse(content)
rules = []
for node in ast.walk(tree):
if (isinstance(node, ast.ClassDef) and
any(isinstance(base, ast.Name) and base.id in ["LintRule",
"GraphRule",
"UnsafeFixRule"] for base in node.bases)):
# Extract class attributes
rule_data = {}
for item in node.body:
if isinstance(item, ast.Assign):
for target in item.targets:
if isinstance(target, ast.Name):
attr_name = target.id
if attr_name in ["code", "name", "description", "severity", "fixable"]:
if isinstance(item.value, ast.Constant):
rule_data[attr_name] = item.value.value
elif isinstance(item.value, ast.Attribute):
# Handle Severity.BREAKING etc
if (isinstance(item.value.value, ast.Name) and
item.value.value.id == "Severity"):
severity_name = item.value.attr
rule_data[attr_name] = Severity(severity_name.lower())
# Extract docstring
docstring = ""
if (node.body and isinstance(node.body[0], ast.Expr) and
isinstance(node.body[0].value, ast.Constant) and
isinstance(node.body[0].value.value, str)):
docstring = node.body[0].value.value
# Create rule info if we have required data
if all(key in rule_data for key in ["code", "name", "description", "severity", "fixable"]):
rules.append(RuleInfo(
code=rule_data["code"],
name=rule_data["name"],
description=rule_data["description"],
severity=rule_data["severity"],
fixable=rule_data["fixable"],
docstring=docstring,
file_path=file_path,
class_name=node.name
))
return rules
def discover_all_rules() -> dict[str, RuleInfo]:
"""Discover all lint rules that are actually registered in the codebase."""
# First, get the registered rule codes from the init files
rules_dir = MARIMO_ROOT / "marimo" / "_lint" / "rules"
breaking_init = rules_dir / "breaking" / "__init__.py"
formatting_init = rules_dir / "formatting" / "__init__.py"
runtime_init = rules_dir / "runtime" / "__init__.py"
wasm_init = rules_dir / "wasm" / "__init__.py"
registered_codes = set()
def process(init_file: Path, prefix: str, registered_codes: set[str]) -> None:
try:
content = init_file.read_text()
# Extract codes from *_RULE_CODES dictionary
for line in content.split('\n'):
if f'"{prefix}' in line and ':' in line:
# Extract the code between quotes
start = line.find(f'"{prefix}')
if start != -1:
end = line.find('"', start + 1)
if end != -1:
code = line[start + 1:end]
registered_codes.add(code)
except Exception as e:
print(f"Warning: Could not parse rules init: {e}")
# Parse the rules init files
process(breaking_init, "MB", registered_codes)
process(runtime_init, "MR", registered_codes)
process(formatting_init, "MF", registered_codes)
process(wasm_init, "MW", registered_codes)
# Now discover rules from source files
rules_dir = MARIMO_ROOT / "marimo" / "_lint" / "rules"
rule_files = list(rules_dir.rglob("*.py"))
all_rules = {}
for file_path in rule_files:
if file_path.name in ["__init__.py", "base.py"]:
continue
try:
rules = extract_rule_info_from_file(file_path)
for rule in rules:
# Only include rules that are actually registered
if rule.code in registered_codes:
all_rules[rule.code] = rule
else:
print(f"Skipping unregistered rule: {rule.code} ({rule.class_name})")
except Exception as e:
print(f"Warning: Could not parse {file_path}: {e}")
return all_rules
def get_severity_info(severity: Severity) -> tuple[str, str, str]:
"""Get display information for a severity level."""
severity_map = {
Severity.BREAKING: ("🚨", "Breaking", "These errors prevent notebook execution"),
Severity.RUNTIME: ("⚠️", "Runtime", "These issues may cause runtime problems"),
Severity.FORMATTING: ("✨", "Formatting", "These are style and formatting issues"),
Severity.WASM: ("🌐", "WASM", "These issues affect WASM/Pyodide compatibility (off by default)"),
}
return severity_map.get(severity, ("❓", "Unknown", ""))
def validate_rule_info(rule: RuleInfo) -> list[str]:
"""Validate that a rule has all required information."""
issues = []
# Check required attributes are present and valid
if not rule.code:
issues.append("Missing rule code")
elif not re.match(r'^M[BRFW]\d{3}$', rule.code):
issues.append(f"Invalid rule code format: {rule.code} (expected MB###, MR###, MF###, or MW###)")
if not rule.name:
issues.append("Missing rule name")
if not rule.description:
issues.append("Missing rule description")
if not isinstance(rule.severity, Severity):
issues.append(f"Invalid severity: {rule.severity}")
if not isinstance(rule.fixable, (bool, str)) or (isinstance(rule.fixable, str) and rule.fixable != "unsafe"):
issues.append(f"Fixable must be a boolean or 'unsafe', got {rule.fixable}")
# Validate docstring exists and is properly formatted
if not rule.docstring:
issues.append("Missing docstring")
else:
lines = rule.docstring.split('\n')
first_line = lines[0].strip() if lines else ""
if first_line and ':' in first_line:
docstring_code = first_line.split(':')[0].strip()
if docstring_code != rule.code:
issues.append(f"Docstring code '{docstring_code}' doesn't match class code '{rule.code}'")
# Validate rule code matches severity prefix
code_prefix = rule.code[:2]
expected_prefixes = {
Severity.BREAKING: "MB",
Severity.RUNTIME: "MR",
Severity.FORMATTING: "MF",
Severity.WASM: "MW",
}
expected_prefix = expected_prefixes.get(rule.severity)
if expected_prefix and code_prefix != expected_prefix:
issues.append(f"Rule code prefix '{code_prefix}' doesn't match severity '{rule.severity.value}' (expected '{expected_prefix}')")
return issues
def get_rule_details(rule: RuleInfo) -> dict[str, Any]:
"""Extract detailed information about a rule."""
if not rule.docstring:
raise ValueError(f"Rule {rule.code} ({rule.class_name}) must have a docstring")
# Remove the first line (rule code/description) and dedent the rest
lines = rule.docstring.split('\n')
full_description = lines[0] if lines else rule.description
# Join everything after the first line and dedent it
remaining_content = '\n'.join(lines[1:]) if len(lines) > 1 else ""
dedented_content = textwrap.dedent(remaining_content)
dedented_lines = dedented_content.split('\n')
# Parse structured sections from dedented content
sections = {}
current_section = None
current_content = []
for line in dedented_lines:
stripped = line.strip()
# Check for section headers
if stripped.startswith('## '):
# Save previous section
if current_section and current_content:
sections[current_section] = '\n'.join(current_content).strip()
# Start new section
current_section = stripped[3:].strip()
current_content = []
elif current_section:
# Add content to current section
current_content.append(line)
# Save last section
if current_section and current_content:
sections[current_section] = '\n'.join(current_content).strip()
return {
'code': rule.code,
'name': rule.name,
'description': rule.description,
'severity': rule.severity,
'fixable': rule.fixable,
'docstring': rule.docstring,
'full_description': full_description,
'sections': sections,
'file_path': str(rule.file_path.relative_to(MARIMO_ROOT)),
'class_name': rule.class_name,
}
def generate_main_index_page(rules_by_severity: dict[Severity, list[dict[str, Any]]]) -> str:
"""Generate the main lint rules index page."""
content = """# Lint Rules
<!-- Autogenerated! Please edit scripts/generate_lint_docs.py instead -->
marimo includes a linter that helps you write better notebooks. The linter checks for various issues that could prevent your notebook from running correctly or cause confusion.
## Usage
Run the linter using the CLI:
```bash
# Check all notebooks in current directory
marimo check .
# Check specific files
marimo check notebook1.py notebook2.py
# Auto-fix fixable issues
marimo check --fix .
```
## Rule Categories
marimo's lint rules are organized into categories based on their severity:
"""
for severity in [Severity.BREAKING, Severity.RUNTIME, Severity.FORMATTING, Severity.WASM]:
if severity not in rules_by_severity:
continue
icon, name, description = get_severity_info(severity)
rules = rules_by_severity[severity]
content += f"### {icon} {name} Rules\n\n"
content += f"{description}.\n\n"
# Create table of rules
content += "| Code | Name | Description | Fixable |\n"
content += "|------|------|-------------|----------|\n"
for rule in sorted(rules, key=lambda r: r['code']):
if rule['fixable'] is True:
fixable_icon = "🛠️"
elif rule['fixable'] == "unsafe":
fixable_icon = "⚠️"
else:
fixable_icon = "❌"
filename = rule['name'].replace("-", "_") + ".md"
rule_link = f"[{rule['code']}](rules/{filename})"
content += f"| {rule_link} | {rule['name']} | {rule['description']} | {fixable_icon} |\n"
content += "\n"
content += """## Legend
- 🛠️ = Automatically fixable with `marimo check --fix`
- ⚠️ = Fixable with `marimo check --fix --unsafe-fixes` (may change code behavior)
- ❌ = Not automatically fixable
## Configuration
Most lint rules are enabled by default. You can configure the linter behavior through marimo's configuration system.
## Related Documentation
- [Understanding Errors](../understanding_errors/index.md) - Detailed explanations of common marimo errors
- [CLI Reference](../../cli.md) - Complete CLI documentation including `marimo check`
"""
return content
def generate_rule_page(rule_details: dict[str, Any]) -> str:
"""Generate documentation page for an individual rule."""
rule = rule_details
icon, severity_name, _ = get_severity_info(rule['severity'])
# Determine fixable status
if rule['fixable'] is True:
fixable_status = '🛠️ Fixable'
elif rule['fixable'] == "unsafe":
fixable_status = '⚠️ Unsafe Fixable'
else:
fixable_status = '❌ Not Fixable'
content = f"""# {rule['code']}: {rule['name']}
{icon} **{severity_name}** {fixable_status}
"""
# Add the first line of the docstring as main description
content += f"{rule['full_description']}\n\n"
# Add structured sections from docstring
sections = rule.get('sections', {})
# Add sections in preferred order
preferred_order = [
'What it does',
'Why is this bad?',
'Examples',
'How to fix',
'References'
]
for section_name in preferred_order:
if section_name in sections:
content += f"## {section_name}\n\n{sections[section_name]}\n\n"
# Add any remaining sections not in the preferred order
for section_name, section_content in sections.items():
if section_name not in preferred_order:
content += f"## {section_name}\n\n{section_content}\n\n"
# Add default sections if not present in docstring
if 'References' not in sections:
content += "## References\n\n"
content += "- [Understanding Errors](../understanding_errors/index.md)\n"
content += f"- [Rule implementation]({_get_github_link(rule)})\n"
return content
def _get_github_link(rule_details: dict[str, Any]) -> str:
"""Generate GitHub link for rule implementation."""
file_path = rule_details['file_path']
return f"https://github.com/marimo-team/marimo/blob/main/{file_path}"
def validate_mkdocs_integration(all_rules: dict[str, RuleInfo]) -> list[str]:
"""Validate that all generated rule pages are included in mkdocs.yml."""
issues = []
# Read mkdocs.yml
mkdocs_path = MARIMO_ROOT / "mkdocs.yml"
if not mkdocs_path.exists():
issues.append("mkdocs.yml not found")
return issues
mkdocs_content = mkdocs_path.read_text()
# Check if main lint rules index is in mkdocs
if "guides/lint_rules/index.md" not in mkdocs_content:
issues.append("Main lint rules page (guides/lint_rules/index.md) not found in mkdocs.yml")
# Check if each rule page is in mkdocs
for code, rule in all_rules.items():
filename = rule.name.replace("-", "_") + ".md"
rule_path = f"guides/lint_rules/rules/{filename}"
if rule_path not in mkdocs_content:
issues.append(f"Rule page {rule_path} not found in mkdocs.yml")
return issues
def main() -> None:
"""Generate all lint rule documentation."""
print("Generating marimo lint rules documentation...")
# Discover all rules
all_rules = discover_all_rules()
print(f"📋 Discovered {len(all_rules)} rules")
# Validate all rules first
validation_issues = {}
for code, rule in all_rules.items():
issues = validate_rule_info(rule)
if issues:
validation_issues[code] = issues
# Check for duplicate rule codes and names across all rules
codes_seen = set()
names_seen = set()
global_issues = []
for code, rule in all_rules.items():
if code in codes_seen:
global_issues.append(f"Duplicate rule code: {code}")
codes_seen.add(code)
if rule.name in names_seen:
global_issues.append(f"Duplicate rule name: {rule.name}")
names_seen.add(rule.name)
# Check mkdocs integration
mkdocs_issues = validate_mkdocs_integration(all_rules)
if validation_issues or global_issues or mkdocs_issues:
print("❌ Validation issues found:")
if global_issues:
print(" Global issues:")
for issue in global_issues:
print(f" - {issue}")
if mkdocs_issues:
print(" mkdocs.yml issues:")
for issue in mkdocs_issues:
print(f" - {issue}")
for code, issues in validation_issues.items():
print(f" {code}:")
for issue in issues:
print(f" - {issue}")
return
print(f"✅ Validated {len(all_rules)} rules and mkdocs.yml integration")
# Organize rules by severity
rules_by_severity: dict[Severity, list[dict[str, Any]]] = {}
for code, rule in all_rules.items():
rule_details = get_rule_details(rule)
severity = rule_details['severity']
if severity not in rules_by_severity:
rules_by_severity[severity] = []
rules_by_severity[severity].append(rule_details)
# Create output directories
docs_dir = MARIMO_ROOT / "docs" / "guides" / "lint_rules"
rules_dir = docs_dir / "rules"
docs_dir.mkdir(parents=True, exist_ok=True)
rules_dir.mkdir(parents=True, exist_ok=True)
# Generate main index page
print("📝 Generating main index page...")
main_content = generate_main_index_page(rules_by_severity)
(docs_dir / "index.md").write_text(main_content)
# Generate individual rule pages
print("📝 Generating individual rule pages...")
for code, rule in all_rules.items():
rule_details = get_rule_details(rule)
rule_content = generate_rule_page(rule_details)
# Use the human-readable name for the filename
filename = rule.name.replace("-", "_") + ".md"
rule_file = rules_dir / filename
rule_file.write_text(rule_content)
print(f" Generated {rule_file.name}")
print(f"✅ Generated documentation for {len(all_rules)} rules")
print(f"📁 Documentation written to: {docs_dir}")
if __name__ == "__main__":
main()