115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
# 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.
|