Skip to content

Commit 2d688d1

Browse files
jjlong150jjlong150
committed
docs: complete wiki restructuring with sanitized titles and updated hierarchy.
1 parent 70183c4 commit 2d688d1

1 file changed

Lines changed: 56 additions & 46 deletions

File tree

‎.devin/wiki.json‎

Lines changed: 56 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
{
2+
"cache_buster": "2024-05-22-T1430-FORCE-REBUILD",
3+
"exclusions": [
4+
"**/Class Modules/**",
5+
"**/Microsoft Excel Objects/**"
6+
],
27
"repo_notes": [
3-
{ "content": "The project is an Excel-based wrapper for Graphviz. Every documentation page must respect the distinction between Excel (the UI/Data layer) and Graphviz (the rendering engine)." },
8+
{ "content": "The project is an Excel-based wrapper for Graphviz. Every documentation page must respect the distinction between Excel (the UI and Data layer) and Graphviz (the rendering engine)." },
49
{ "content": "Technical Consistency: Always refer to the primary data entry points as 'Items' and 'Related Items' rather than 'From' and 'To' to match the worksheet headers." },
5-
{ "content": "Cross-Platform Logic: When documenting any code that triggers a shell command or file I/O, mention the conditional logic for Windows (Shell/CreatePipe) vs. macOS (AppleScript bridge)." },
10+
{ "content": "Cross-Platform Logic: When documenting any code that triggers a shell command or file input output, mention the conditional logic for Windows (Windows Shell via CreatePipe) vs. macOS (AppleScript bridge)." },
611
{ "content": "Module Mapping: Every functional feature should be linked to its corresponding VBA module (e.g., modRibbonTab*.bas for UI, modCreateGraph.bas for parsing, Graphviz.cls for execution)." },
712
{ "content": "State Management: Remind that the tool relies on a 'Settings' worksheet for persistent state and a global 'internalMyRibbon' variable for UI state." },
813
{ "content": "Error Handling Philosophy: Emphasize that the tool uses 'ValidateData' and local error handling to prevent VBA global state loss, which would break the Ribbon reference." },
914
{ "content": "Graphviz Syntax: When discussing attributes (color, shape, etc.), ensure they align with the official DOT language specifications." },
1015
{ "content": "Community Feedback: Mention that community feedback and feature requests are captured via GitHub issues, and via Giscus-powered comments on the official website blog pages." },
1116
{ "content": "Version Awareness: Reference v8.0+ enhancements including Style Designer galleries, Graphviz.cls refactor, SQL connection pooling, unlimited CLUSTERn, SVG editor form, silent mode, and new ribbon tabs (Info, Console, Diagnostics, Styles)." },
12-
{ "content": "Common Pitfalls & Best Practices: Include Graphviz node ID rules (must start with letter or underscore, quote digits), layout reproducibility tips (start=regular), SVG image embedding via base64 in post-processor, and named-range contract for safe sheet modifications." }
17+
{ "content": "Common Pitfalls and Best Practices: Include Graphviz node ID rules (must start with letter or underscore, quote digits), layout reproducibility tips (start=regular), SVG image embedding via base64 in post-processor, and named-range contract for safe sheet modifications." },
18+
{ "content": "Project structure update: All VBA source files are now organized in CamelCase directories (e.g., ClassModules, MicrosoftExcelObjects) to improve cross-platform compatibility." }
1319
],
1420
"pages": [
1521
{
@@ -22,7 +28,7 @@
2228
]
2329
},
2430
{
25-
"title": "Getting Started & Installation",
31+
"title": "Getting Started and Installation",
2632
"purpose": "Onboarding guide covering setup, dependencies, and cross-platform compatibility.",
2733
"parent": "Overview",
2834
"page_notes": [
@@ -32,7 +38,7 @@
3238
]
3339
},
3440
{
35-
"title": "Core Concepts & Terminology",
41+
"title": "Core Concepts and Terminology",
3642
"purpose": "Foundational glossary of graph terms and project-specific concepts.",
3743
"parent": "Overview",
3844
"page_notes": [
@@ -41,17 +47,17 @@
4147
]
4248
},
4349
{
44-
"title": "Architecture & Data Flow",
50+
"title": "Architecture and Data Flow",
4551
"purpose": "High-level technical map of the system's layers and transformation pipeline.",
4652
"page_notes": [
4753
{ "content": "Transformation Pipeline: Worksheet data → modCreateGraph.bas parsing → DOT file → Graphviz executable → output image (or worksheet)." },
48-
{ "content": "Multi-Tiered Layers: Excel UI/Data, VBA Logic (modules + classes), and External Graphviz engine." }
54+
{ "content": "Multi-Tiered Layers: Excel UI and Data, VBA Logic (modules + classes), and External Graphviz engine." }
4955
]
5056
},
5157
{
52-
"title": "VBA Class Hierarchy & Key Objects",
58+
"title": "VBA Class Hierarchy and Key Objects",
5359
"purpose": "Overview of the object-oriented core and data structures.",
54-
"parent": "Architecture & Data Flow",
60+
"parent": "Architecture and Data Flow",
5561
"page_notes": [
5662
{ "content": "Key Classes: Graphviz.cls (execution), Cluster.cls, Style object model, and dataRow UDT as worksheet-to-DOT intermediary." },
5763
{ "content": "Integration: Classes work with named ranges and modCreateGraph.bas while protecting Ribbon state via local error handling." }
@@ -60,41 +66,41 @@
6066
{
6167
"title": "Graph Generation Pipeline",
6268
"purpose": "End-to-end lifecycle from worksheet parsing to rendering.",
63-
"parent": "Architecture & Data Flow",
69+
"parent": "Architecture and Data Flow",
6470
"page_notes": [
6571
{ "content": "Row Classification: modCreateGraph.bas handles TYPE_NODE, TYPE_EDGE, and TYPE_SUBGRAPH rows." },
6672
{ "content": "File Handshake: Writes DOT string to temp file and invokes Graphviz via platform-specific execution." }
6773
]
6874
},
6975
{
70-
"title": "Graphviz Class & Process Execution",
76+
"title": "Graphviz Class and Process Execution",
7177
"purpose": "Low-level execution logic for communicating with Graphviz binaries.",
72-
"parent": "Architecture & Data Flow",
78+
"parent": "Architecture and Data Flow",
7379
"page_notes": [
74-
{ "content": "Windows Path: Uses modExecuteAndCapture.bas with CreatePipe/CreateProcessA and PeekNamedPipe/ReadFile for deadlock-free stdout/stderr capture." },
80+
{ "content": "Windows Path: Uses modExecuteAndCapture.bas with CreatePipe, CreateProcessA, PeekNamedPipe, and ReadFile routines for deadlock-free stdout and stderr capture." },
7581
{ "content": "macOS Path: AppleScript bridge. Graphviz.cls refactor centralizes cross-platform logic." }
7682
]
7783
},
7884
{
79-
"title": "Worksheet Architecture & Named Ranges",
85+
"title": "Worksheet Architecture and Named Ranges",
8086
"purpose": "Guide to sheet structure and the named-range contract.",
81-
"parent": "Architecture & Data Flow",
87+
"parent": "Architecture and Data Flow",
8288
"page_notes": [
8389
{ "content": "Named Range API: Over 700 named ranges act as a stable contract, allowing UI changes without breaking VBA code." },
8490
{ "content": "Maintenance Note: Avoid hard-coded cell addresses; always use named ranges." }
8591
]
8692
},
8793
{
88-
"title": "Constants, Data Types & Utility Modules",
94+
"title": "Constants, Data Types and Utility Modules",
8995
"purpose": "Foundational building blocks and utility organization.",
90-
"parent": "Architecture & Data Flow",
96+
"parent": "Architecture and Data Flow",
9197
"page_notes": [
9298
{ "content": "Constant Prefixes: SETTINGS_ and DESIGNER_ map directly to named ranges." },
93-
{ "content": "Utilities: String helpers, picture management, OptimizeCode_Begin/End, and ADO connection pooling." }
99+
{ "content": "Utilities: String helpers, picture management, OptimizeCode_Begin, OptimizeCode_End, and ADO connection pooling." }
94100
]
95101
},
96102
{
97-
"title": "User Interface: Ribbon Tabs",
103+
"title": "User Interface Ribbon Tabs",
98104
"purpose": "Overview of custom Ribbon architecture and callback system.",
99105
"page_notes": [
100106
{ "content": "Callback Model: Dedicated modules (e.g., modRibbonTabGraphviz.bas) bridge UI to logic." },
@@ -104,7 +110,7 @@
104110
{
105111
"title": "Graphviz Ribbon Tab",
106112
"purpose": "Guide to layout engines and publishing functions.",
107-
"parent": "User Interface: Ribbon Tabs",
113+
"parent": "User Interface Ribbon Tabs",
108114
"page_notes": [
109115
{ "content": "Layout Engines: dot, neato, fdp, sfdp, twopi, circo, osage, patchwork." },
110116
{ "content": "Publish Group: graphToWorksheet, graphToFile, graphAllViewsToFile." }
@@ -113,19 +119,22 @@
113119
{
114120
"title": "Style Designer Ribbon Tab",
115121
"purpose": "Technical guide to the Style Designer and gallery system.",
116-
"parent": "User Interface: Ribbon Tabs",
122+
"parent": "User Interface Ribbon Tabs",
117123
"page_notes": [
118124
{ "content": "Gallery Previews: Uses ChartObjects for color swatches and Graphviz for font previews (v8.0+ enhancements)." },
119125
{ "content": "RestoreStyleDesigner: Re-hydrates ribbon settings when a style is selected." }
120126
]
121127
},
122128
{
123129
"title": "SQL Ribbon Tab",
124-
"purpose": "Interface and floating action button framework.",
125-
"parent": "User Interface: Ribbon Tabs",
130+
"purpose": "Technical guide to the SQL-driven graph generation and connection management.",
131+
"parent": "User Interface Ribbon Tabs",
126132
"page_notes": [
127-
{ "content": "Filter System: Dynamic dropdowns via filterValues Dictionary." },
128-
{ "content": "Floating Buttons: UpdateFloatingButtonsOnSheet enables on-sheet SQL execution (Windows-only)." }
133+
{ "content": "Query Engine: Uses modWorksheetSQL.bas and modWorksheetSQLClusters.bas to execute user-defined SQL against external databases or local Excel tables via ADO." },
134+
{ "content": "Dynamic Mapping: SQL results are mapped to 'Item' and 'Related Item' fields to feed the Graphviz pipeline automatically." },
135+
{ "content": "Connection Pooling: Leverages a centralized connection string managed in code, which finds the best Provider for the user's OS and software." },
136+
{ "content": "Floating Action Button (FAB): Explains the 'Run SQL' overlay that allows for rapid iterative testing of graph queries." },
137+
{ "content": "Platform Limitation: Clearly state that SQL features are Windows-only due to dependency on ActiveX Data Objects (ADO)." }
129138
]
130139
},
131140
{
@@ -137,15 +146,15 @@
137146
]
138147
},
139148
{
140-
"title": "Defining Nodes & Edges",
149+
"title": "Defining Nodes and Edges",
141150
"purpose": "Node and Edge data models with advanced syntax.",
142151
"parent": "Working with the Data Worksheet",
143152
"page_notes": [
144153
{ "content": "Advanced Support: Port syntax (node:port), HTML-like labels in angle brackets, and GetDataRow structure." }
145154
]
146155
},
147156
{
148-
"title": "Subgraphs & Clustering",
157+
"title": "Subgraphs and Clustering",
149158
"purpose": "Hierarchical grouping and stack-based parsing.",
150159
"parent": "Working with the Data Worksheet",
151160
"page_notes": [
@@ -154,7 +163,7 @@
154163
]
155164
},
156165
{
157-
"title": "Styles & the Style Gallery",
166+
"title": "Styles and the Style Gallery",
158167
"purpose": "Style object model, caching, and preview lifecycle.",
159168
"parent": "Working with the Data Worksheet",
160169
"page_notes": [
@@ -172,13 +181,14 @@
172181
{
173182
"title": "SQL Data Integration",
174183
"purpose": "Windows-only ADO-based external data connectivity.",
184+
"parent": "Architecture and Data Flow",
175185
"page_notes": [
176-
{ "content": "Windows-Only: SQL/ADO unavailable on macOS." },
186+
{ "content": "Windows-Only: SQL ADO unavailable on macOS." },
177187
{ "content": "Supported Sources: External Excel workbooks and Access databases." }
178188
]
179189
},
180190
{
181-
"title": "SQL Engine & Connection Pooling",
191+
"title": "SQL Engine and Connection Pooling",
182192
"purpose": "ADO execution engine details.",
183193
"parent": "SQL Data Integration",
184194
"page_notes": [
@@ -191,53 +201,53 @@
191201
"purpose": "Specialized query modes and recent enhancements.",
192202
"parent": "SQL Data Integration",
193203
"page_notes": [
194-
{ "content": "RecursiveSearch: Anchor/recursive member pattern for tree traversal." },
195-
{ "content": "Enhancements: Placeholders, concatenation/iterative queries, CREATE EDGES/RANK, and multi-level CLUSTERn." }
204+
{ "content": "RecursiveSearch: Anchor and recursive member pattern for tree traversal." },
205+
{ "content": "Enhancements: Placeholders, concatenation, iterative queries, enumeration queries, CREATE EDGES, CREATE RANK, and multi-level CLUSTERn." }
196206
]
197207
},
198208
{
199-
"title": "Output, Publishing & Post-Processing",
209+
"title": "Output, Publishing and Post-Processing",
200210
"purpose": "Rendering, publishing, and SVG manipulation.",
201211
"page_notes": [
202-
{ "content": "SVG Post-Processor: XML find/replace and JS injection for interactivity and base64 image embedding (Excel reliability)." },
212+
{ "content": "SVG Post-Processor: XML find and replace for JS injection for interactivity and base64 image embedding (Excel reliability)." },
203213
{ "content": "Formats: EMF for Office integration; SVG editor form available for manual tweaks." }
204214
]
205215
},
206216
{
207-
"title": "Event-Driven Architecture & AutoDraw",
217+
"title": "Event-Driven Architecture and AutoDraw",
208218
"purpose": "Worksheet events and real-time reactivity.",
209219
"parent": "Working with the Data Worksheet",
210220
"page_notes": [
211221
{ "content": "Lifecycle: Worksheet_Change and Worksheet_SelectionChange drive AutoDraw while protecting internalMyRibbon via ValidateData." }
212222
]
213223
},
214224
{
215-
"title": "Troubleshooting, Best Practices & Graphviz Quirks",
216-
"purpose": "Practical guidance for common issues.",
217-
"parent": "Settings & Diagnostics",
225+
"title": "Settings and Diagnostics",
226+
"purpose": "Configuration, health checks, and system state.",
218227
"page_notes": [
219-
{ "content": "Node IDs: Start with letter/underscore; quote digits. Use start=regular for reproducible layouts in neato/fdp." },
220-
{ "content": "Diagnostics: Worksheet tests OS/Excel/Graphviz versions; check Console for stdout/stderr." }
228+
{ "content": "GetSettings UDT: Cached repository for all configuration values." },
229+
{ "content": "Diagnostics Worksheet: Automated version and environment tests; supports silent mode." }
221230
]
222231
},
223232
{
224-
"title": "Settings & Diagnostics",
225-
"purpose": "Configuration, health checks, and system state.",
233+
"title": "Troubleshooting, Best Practices and Graphviz Quirks",
234+
"purpose": "Practical guidance for common issues.",
235+
"parent": "Settings and Diagnostics",
226236
"page_notes": [
227-
{ "content": "GetSettings UDT: Cached repository for all configuration values." },
228-
{ "content": "Diagnostics Worksheet: Automated version and environment tests; supports silent mode." }
237+
{ "content": "Node IDs: Start with letter or underscore; quote digits." },
238+
{ "content": "Diagnostics: Worksheet tests OS, Excel, and Graphviz versions; check Console for stdout and stderr messages." }
229239
]
230240
},
231241
{
232-
"title": "Data Exchange (JSON Import/Export)",
242+
"title": "Data Exchange (JSON Import and Export)",
233243
"purpose": "E2GXF format for portability and version control.",
234244
"page_notes": [
235245
{ "content": "Use Cases: Git-friendly templates and sharing via text files." },
236246
{ "content": "Implementation: modExchangeImport.bas handles carriage-return kludge for multi-line cells." }
237247
]
238248
},
239249
{
240-
"title": "Web Presence & Community",
250+
"title": "Web Presence and Community",
241251
"purpose": "Public ecosystem and contribution channels.",
242252
"page_notes": [
243253
{ "content": "Site: VitePress on GitHub Pages at exceltographviz.com with custom domain." },

0 commit comments

Comments
 (0)