Initial commit

skills/ontological-documentation/scripts/README.md

@@ -0,0 +1,114 @@
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:
+```bash
+python generate_ontology_diagram.py ontology.json --format mermaid
+# Creates: ontology_mermaid.md
+```
+
+PlantUML:
+```bash
+python generate_ontology_diagram.py ontology.json --format plantuml
+# Creates: ontology_plantuml.puml
+```
+
+GraphViz DOT:
+```bash
+python generate_ontology_diagram.py ontology.json --format dot
+# Creates: ontology.dot
+```
+
+JSON-LD:
+```bash
+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
+
+```bash
+# 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](../SKILL.md) by providing automated tools for concept extraction and visualization. Use them to bootstrap your ontological documentation process.