Ontological Documentation Scripts

This directory contains utility scripts for automated concept extraction and diagram generation.

Scripts

extract_concepts.py

Analyzes codebases to extract domain concepts, entities, and relationships for building ontological documentation.

Features:

Supports Python and JavaScript/TypeScript
Extracts classes, functions, inheritance relationships, and imports
Builds ontological structure with relationships (is_a, part_of, depends_on, associates_with)
Generates JSON ontology representation
Creates Mermaid diagrams

Usage:

# Analyze a single file
python extract_concepts.py /path/to/file.py

# Analyze a directory
python extract_concepts.py /path/to/codebase

# Save output to file
python extract_concepts.py /path/to/codebase > ontology.json

Output:

JSON ontology structure
Mermaid diagram representation

generate_ontology_diagram.py

Generates visual representations of ontologies in various formats.

Features:

Supports multiple diagram formats (Mermaid, PlantUML, GraphViz DOT, JSON-LD)
Customizable relationship symbols
Semantic web compatibility (JSON-LD output)
Styled diagrams with concept type differentiation

Usage:

# Generate all formats
python generate_ontology_diagram.py ontology.json

# Generate specific format
python generate_ontology_diagram.py ontology.json --format mermaid

# Specify output directory
python generate_ontology_diagram.py ontology.json --output ./diagrams

# Available formats: mermaid, plantuml, dot, json-ld, all

Output Examples:

Mermaid:

python generate_ontology_diagram.py ontology.json --format mermaid
# Creates: ontology_mermaid.md

PlantUML:

python generate_ontology_diagram.py ontology.json --format plantuml
# Creates: ontology_plantuml.puml

GraphViz DOT:

python generate_ontology_diagram.py ontology.json --format dot
# Creates: ontology.dot

JSON-LD:

python generate_ontology_diagram.py ontology.json --format json-ld
# Creates: ontology_jsonld.json

Requirements

Both scripts use only Python standard library modules:

ast - Python AST parsing
re - Regular expressions
json - JSON processing
pathlib - Path handling
argparse - Command-line argument parsing

No additional dependencies required!

Example Workflow

# 1. Extract concepts from codebase
python extract_concepts.py /path/to/codebase > ontology.json

# 2. Generate diagrams
python generate_ontology_diagram.py ontology.json --output ./docs/diagrams

# 3. Review generated documentation
ls ./docs/diagrams/
# ontology_mermaid.md
# ontology_plantuml.puml
# ontology.dot
# ontology_jsonld.json

Integration with Skill

These scripts support the main SKILL.md by providing automated tools for concept extraction and visualization. Use them to bootstrap your ontological documentation process.

2.9 KiB Raw Blame History