0
# Documentation Generation
1

2
Ontospy provides comprehensive documentation generation capabilities for creating professional HTML documentation, interactive visualizations, and various export formats from RDF ontologies. The system supports multiple output formats including Bootstrap-themed websites, D3.js visualizations, and markdown documentation.
3

4
## Capabilities
5

6
### Visualization Factory
7

8
Central factory class for building ontology visualizations with customizable themes and output formats.
9

10
```python { .api }
11
from ontospy.gendocs.viz_factory import VizFactory
12

13
class VizFactory:
14
    def __init__(self, ontospy_graph, title=""):
15
        """
16
        Initialize visualization factory.
17
        
18
        Parameters:
19
        - ontospy_graph (Ontospy): Analyzed ontology graph
20
        - title (str): Custom title for visualization
21
        """
22
    
23
    def infer_best_title(self):
24
        """
25
        Automatically infer appropriate title from ontology metadata.
26
        
27
        Returns:
28
        str: Inferred title based on ontology properties
29
        """
30
    
31
    def build(self, output_path=""):
32
        """
33
        Generate visualization files in specified directory.
34
        
35
        Parameters:
36
        - output_path (str): Directory path for output files
37
        """
38
    
39
    def preview(self):
40
        """Open generated visualization in default web browser."""
41
```
42

43
### Documentation Actions
44

45
High-level functions for managing visualization types, themes, and building documentation outputs.
46

47
```python { .api }
48
from ontospy.gendocs.actions import (
49
    show_types, show_themes, build_visualization,
50
    ask_visualization, select_visualization
51
)
52

53
def show_types():
54
    """Display all available visualization types with descriptions."""
55

56
def show_themes():
57
    """Display all available Bootstrap themes for HTML output."""
58

59
def random_theme():
60
    """
61
    Get random Bootstrap theme selection.
62
    
63
    Returns:
64
    str: Random theme name
65
    """
66

67
def validate_theme(theme_try, default):
68
    """
69
    Validate theme selection against available options.
70
    
71
    Parameters:
72
    - theme_try (str): Requested theme name
73
    - default (str): Fallback theme if invalid
74
    
75
    Returns:
76
    str: Valid theme name
77
    """
78

79
def ask_visualization():
80
    """
81
    Interactive prompt for visualization type selection.
82
    
83
    Returns:
84
    int: Selected visualization type index
85
    """
86

87
def select_visualization(n):
88
    """
89
    Select visualization type by index number.
90
    
91
    Parameters:
92
    - n (int): Visualization type index
93
    
94
    Returns:
95
    class: Visualization class for the selected type
96
    """
97

98
def build_visualization(g, viz_index, path=None, title="", theme=""):
99
    """
100
    Build complete visualization output.
101
    
102
    Parameters:
103
    - g (Ontospy): Analyzed ontology graph
104
    - viz_index (int): Visualization type index
105
    - path (str): Output directory path
106
    - title (str): Custom title for documentation
107
    - theme (str): Bootstrap theme name for HTML output
108
    """
109
```
110

111
### HTML Documentation
112

113
Generate comprehensive HTML documentation with Bootstrap styling, interactive navigation, and professional presentation.
114

115
```python { .api }
116
# HTML Single Page Documentation
117
class Viz_html_single:
118
    """Generate single-page HTML documentation with complete ontology information."""
119

120
# HTML Multi-Page Documentation  
121
class Viz_html_multi:
122
    """Generate multi-page HTML website with separate pages for each entity type."""
123
```
124

125
Usage example:
126

127
```python
128
import ontospy
129
from ontospy.gendocs.actions import build_visualization, show_types
130

131
# Load ontology
132
g = ontospy.Ontospy("ontology.owl", build_all=True)
133

134
# Show available visualization types
135
show_types()
136

137
# Build HTML multi-page documentation
138
build_visualization(
139
    g, 
140
    viz_index=2,  # HTML multi-page
141
    path="./docs",
142
    title="My Ontology Documentation", 
143
    theme="cerulean"
144
)
145

146
# Using VizFactory directly
147
from ontospy.gendocs.viz_factory import VizFactory
148

149
factory = VizFactory(g, title="Custom Title")
150
factory.build(output_path="./output")
151
factory.preview()  # Open in browser
152
```
153

154
### Interactive Visualizations
155

156
Generate D3.js-based interactive visualizations for exploring ontology structure and relationships.
157

158
```python { .api }
159
# D3.js Visualizations
160
class Viz_d3bar_hierarchy:
161
    """Bar chart hierarchy visualization showing class/property relationships."""
162

163
class Viz_d3bubble_chart:
164
    """Bubble chart visualization with size representing entity importance."""
165

166
class Viz_d3dendogram:
167
    """Tree dendrogram visualization of hierarchical relationships."""
168

169
class Viz_d3pack_hierarchy:
170
    """Packed circle hierarchy showing nested ontological structures."""
171

172
class Viz_d3partition_table:
173
    """Partition table visualization with interactive navigation."""
174

175
class Viz_d3rotating_cluster:
176
    """Rotating cluster diagram for dynamic hierarchy exploration."""
177
```
178

179
### Network Graph Visualization
180

181
Generate network graph visualizations using Sigma.js for exploring ontology relationships and connectivity.
182

183
```python { .api }
184
class Viz_sigmajs:
185
    """
186
    Sigma.js network graph visualization showing entities as nodes 
187
    and relationships as edges with interactive exploration capabilities.
188
    """
189
```
190

191
### Markdown Export
192

193
Generate markdown documentation suitable for documentation websites, GitHub repositories, and technical documentation systems.
194

195
```python { .api }
196
class Viz_markdown:
197
    """Generate markdown documentation with structured ontology information."""
198
```
199

200
## Complete Workflow Example
201

202
```python
203
import ontospy
204
from ontospy.gendocs.actions import (
205
    show_types, show_themes, build_visualization
206
)
207

208
# 1. Load and analyze ontology
209
print("Loading ontology...")
210
g = ontospy.Ontospy("http://xmlns.com/foaf/0.1/", build_all=True)
211

212
# 2. Show available options
213
print("Available visualization types:")
214
show_types()
215

216
print("\\nAvailable themes:")
217
show_themes()
218

219
# 3. Generate multiple documentation formats
220
print("\\nGenerating documentation...")
221

222
# HTML multi-page with custom theme
223
build_visualization(
224
    g, 
225
    viz_index=2,  # HTML multi-page
226
    path="./docs/html-multi",
227
    title="FOAF Ontology Documentation",
228
    theme="flatly"
229
)
230

231
# Single page HTML
232
build_visualization(
233
    g,
234
    viz_index=1,  # HTML single page  
235
    path="./docs/html-single",
236
    title="FOAF Ontology - Complete Reference"
237
)
238

239
# Interactive D3 dendrogram
240
build_visualization(
241
    g,
242
    viz_index=5,  # D3 dendrogram
243
    path="./docs/d3-tree", 
244
    title="FOAF Class Hierarchy"
245
)
246

247
# Network graph visualization
248
build_visualization(
249
    g,
250
    viz_index=10,  # Sigma.js network
251
    path="./docs/network",
252
    title="FOAF Relationship Network"
253
)
254

255
# Markdown export
256
build_visualization(
257
    g,
258
    viz_index=3,  # Markdown
259
    path="./docs/markdown",
260
    title="FOAF Ontology Reference"
261
)
262

263
print("Documentation generation complete!")
264
```
265

266
## Visualization Types
267

268
The following visualization types are available (use `show_types()` for current list):
269

270
1. **HTML Single Page**: Complete ontology documentation in a single HTML file
271
2. **HTML Multi-Page**: Professional website with separate pages for classes, properties, etc.
272
3. **Markdown**: Structured markdown suitable for GitHub/documentation sites
273
4. **D3 Bar Hierarchy**: Interactive bar chart showing class/property hierarchies
274
5. **D3 Bubble Chart**: Bubble visualization with entity importance sizing
275
6. **D3 Dendrogram**: Tree diagram of hierarchical relationships
276
7. **D3 Pack Hierarchy**: Packed circle hierarchy visualization
277
8. **D3 Partition Table**: Interactive partition table navigation
278
9. **D3 Rotating Cluster**: Dynamic rotating cluster diagram
279
10. **Sigma.js Network**: Interactive network graph with node/edge exploration
280

281
## Theme Options
282

283
For HTML visualizations, the following Bootstrap themes are available (use `show_themes()` for current list):
284

285
- **default**: Standard Bootstrap styling
286
- **cerulean**: Blue-toned professional theme  
287
- **cosmo**: Clean, modern appearance
288
- **flatly**: Flat design aesthetic
289
- **journal**: Newspaper-style layout
290
- **readable**: Optimized for text readability
291
- **simplex**: Minimalist design
292
- **spacelab**: Gray-toned professional theme
293
- **united**: Orange-accented theme
294
- **yeti**: Clean, spacious layout
295

296
## Output Structure
297

298
Generated documentation typically includes:
299

300
- **index.html**: Main entry point with ontology overview
301
- **classes.html**: Complete class listings and details
302
- **properties.html**: Property definitions and relationships  
303
- **individuals.html**: Instance data (if included)
304
- **static/**: CSS, JavaScript, and asset files
305
- **media/**: Visualization-specific resources
306

307
Interactive visualizations include additional JavaScript libraries and configuration files for dynamic functionality.