pbip-doc 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. pbip_doc-0.2.0/LICENSE +21 -0
  2. pbip_doc-0.2.0/PKG-INFO +392 -0
  3. pbip_doc-0.2.0/README.md +360 -0
  4. pbip_doc-0.2.0/pbip_doc/__init__.py +54 -0
  5. pbip_doc-0.2.0/pbip_doc/__main__.py +7 -0
  6. pbip_doc-0.2.0/pbip_doc/cli.py +804 -0
  7. pbip_doc-0.2.0/pbip_doc/codebase_scanner.py +955 -0
  8. pbip_doc-0.2.0/pbip_doc/dax_formatter.py +596 -0
  9. pbip_doc-0.2.0/pbip_doc/docgen/__init__.py +59 -0
  10. pbip_doc-0.2.0/pbip_doc/docgen/config.py +979 -0
  11. pbip_doc-0.2.0/pbip_doc/docgen/engine.py +349 -0
  12. pbip_doc-0.2.0/pbip_doc/docgen/expression_doc.py +912 -0
  13. pbip_doc-0.2.0/pbip_doc/docgen/function_doc.py +435 -0
  14. pbip_doc-0.2.0/pbip_doc/docgen/html_assets.py +1770 -0
  15. pbip_doc-0.2.0/pbip_doc/docgen/html_builders.py +4694 -0
  16. pbip_doc-0.2.0/pbip_doc/docgen/html_engine.py +505 -0
  17. pbip_doc-0.2.0/pbip_doc/docgen/html_layout.py +522 -0
  18. pbip_doc-0.2.0/pbip_doc/docgen/index_doc.py +1055 -0
  19. pbip_doc-0.2.0/pbip_doc/docgen/layout_engine.py +748 -0
  20. pbip_doc-0.2.0/pbip_doc/docgen/link_resolver.py +352 -0
  21. pbip_doc-0.2.0/pbip_doc/docgen/measure_doc.py +498 -0
  22. pbip_doc-0.2.0/pbip_doc/docgen/relationship_config.py +211 -0
  23. pbip_doc-0.2.0/pbip_doc/docgen/relationship_diagram.py +2062 -0
  24. pbip_doc-0.2.0/pbip_doc/docgen/section_engine.py +134 -0
  25. pbip_doc-0.2.0/pbip_doc/docgen/table_doc.py +1350 -0
  26. pbip_doc-0.2.0/pbip_doc/docgen/utils.py +531 -0
  27. pbip_doc-0.2.0/pbip_doc/docgen/visual_doc.py +691 -0
  28. pbip_doc-0.2.0/pbip_doc/docgen/workspace_engine.py +1926 -0
  29. pbip_doc-0.2.0/pbip_doc/m_formatter.py +269 -0
  30. pbip_doc-0.2.0/pbip_doc/m_lineage.py +549 -0
  31. pbip_doc-0.2.0/pbip_doc/m_parser.py +1142 -0
  32. pbip_doc-0.2.0/pbip_doc/m_step_graph.py +881 -0
  33. pbip_doc-0.2.0/pbip_doc/m_table_parser.py +353 -0
  34. pbip_doc-0.2.0/pbip_doc/measure_analyzer.py +261 -0
  35. pbip_doc-0.2.0/pbip_doc/model_schema.py +637 -0
  36. pbip_doc-0.2.0/pbip_doc/parser.py +1383 -0
  37. pbip_doc-0.2.0/pbip_doc/report_parser.py +1711 -0
  38. pbip_doc-0.2.0/pbip_doc/report_schema.py +215 -0
  39. pbip_doc-0.2.0/pbip_doc/star_schema.py +601 -0
  40. pbip_doc-0.2.0/pbip_doc/tmdl_lexer.py +469 -0
  41. pbip_doc-0.2.0/pbip_doc.egg-info/PKG-INFO +392 -0
  42. pbip_doc-0.2.0/pbip_doc.egg-info/SOURCES.txt +61 -0
  43. pbip_doc-0.2.0/pbip_doc.egg-info/dependency_links.txt +1 -0
  44. pbip_doc-0.2.0/pbip_doc.egg-info/entry_points.txt +4 -0
  45. pbip_doc-0.2.0/pbip_doc.egg-info/top_level.txt +1 -0
  46. pbip_doc-0.2.0/pyproject.toml +52 -0
  47. pbip_doc-0.2.0/setup.cfg +4 -0
  48. pbip_doc-0.2.0/tests/test_cli.py +121 -0
  49. pbip_doc-0.2.0/tests/test_codebase_scanner.py +126 -0
  50. pbip_doc-0.2.0/tests/test_composite_and_lineage_fixes.py +1562 -0
  51. pbip_doc-0.2.0/tests/test_dax_formatter.py +114 -0
  52. pbip_doc-0.2.0/tests/test_html_docgen.py +1706 -0
  53. pbip_doc-0.2.0/tests/test_layout_engine.py +412 -0
  54. pbip_doc-0.2.0/tests/test_link_resolver.py +145 -0
  55. pbip_doc-0.2.0/tests/test_m_lineage.py +217 -0
  56. pbip_doc-0.2.0/tests/test_m_parser.py +264 -0
  57. pbip_doc-0.2.0/tests/test_m_step_graph.py +197 -0
  58. pbip_doc-0.2.0/tests/test_pbip_doc.py +3603 -0
  59. pbip_doc-0.2.0/tests/test_refinements.py +354 -0
  60. pbip_doc-0.2.0/tests/test_relationship_diagram.py +745 -0
  61. pbip_doc-0.2.0/tests/test_report_parser.py +1664 -0
  62. pbip_doc-0.2.0/tests/test_tmdl_lexer.py +189 -0
  63. pbip_doc-0.2.0/tests/test_workspace_docgen.py +797 -0
pbip_doc-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Simone Mazzoleni Ferracini
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,392 @@
1
+ Metadata-Version: 2.4
2
+ Name: pbip-doc
3
+ Version: 0.2.0
4
+ Summary: Pure Python documentation generator and metadata extractor for Power BI Project (PBIP) and Fabric semantic models.
5
+ Author-email: Simone Mazzoleni <mazzolenif.simone@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/mazzolenifsimone/pbip-doc
8
+ Project-URL: Repository, https://github.com/mazzolenifsimone/pbip-doc
9
+ Project-URL: Issues, https://github.com/mazzolenifsimone/pbip-doc/issues
10
+ Project-URL: Documentation, https://github.com/mazzolenifsimone/pbip-doc#readme
11
+ Keywords: power-bi,pbip,microsoft-fabric,tmdl,tmsl,dax,power-query,documentation,lineage,rag
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Information Technology
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: License :: OSI Approved :: MIT License
24
+ Classifier: Operating System :: OS Independent
25
+ Classifier: Topic :: Database
26
+ Classifier: Topic :: Documentation
27
+ Classifier: Topic :: Software Development :: Documentation
28
+ Requires-Python: >=3.8
29
+ Description-Content-Type: text/markdown
30
+ License-File: LICENSE
31
+ Dynamic: license-file
32
+
33
+ # pbip-doc
34
+
35
+ > **Automated Documentation, Lineage Resolution, and Knowledge Extraction for Microsoft Fabric & Power BI Projects (`.pbip`).**
36
+
37
+ [![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
38
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/LICENSE)
39
+ [![Dependencies](https://img.shields.io/badge/dependencies-zero%20(standard%20library)-brightgreen.svg)]()
40
+ [![Air-Gap Safe](https://img.shields.io/badge/air--gap-100%25%20offline-success.svg)]()
41
+ [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
42
+ [![Architecture](https://img.shields.io/badge/architecture-Zero--JS%20HTML%20%7C%20RAG--Ready%20MD-blueviolet.svg)](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/ARCHITECTURE.md)
43
+
44
+ ![pbip-doc โ€” Docs for people and AI](https://raw.githubusercontent.com/mazzolenifsimone/pbip-doc/v0.2.0/assets/pbip_doc_banner.jpg)
45
+
46
+ ---
47
+
48
+ ## ๐ŸŽฏ Context & Mission
49
+
50
+ With the emergence of Microsoft Fabric and Power BI Project files (`.pbip`), Business Intelligence development has shifted to modern software engineering practices: semantic models and reports are finally tracked as plain-text source files (TMDL, TMSL/BIM, PBIR) within Git repositories.
51
+
52
+ However, version-controlled text files do not automatically provide accessible knowledge:
53
+
54
+ * **The Human Knowledge Access Problem**: Business analysts, data engineers, and BI architects need holistic, immediate visibility into the semantic model:
55
+ * **Obscure Calculation Hierarchies**: Business logic is buried across deeply nested DAX measures, table dependencies, and calculation groups, obscuring true calculation depth and dependency chains.
56
+ * **Buried ETL Data Lineage**: Power Query (M) transformation steps, source connections, and dataflow ingestions are opaque and difficult to trace at a glance across separate table files.
57
+ * **Heavyweight Desktop Lock-in**: Inspecting a data model or report schema traditionally requires launching heavyweight GUI tools (Power BI Desktop, Tabular Editor) that cannot run in headless CI/CD runners or automated environments.
58
+ * **Absence of Dedicated Documentation Tooling**: The BI ecosystem lacks headless, CLI-driven living documentation generators. Teams are forced to manually maintain static Word/Excel data dictionaries or wiki pages that drift out of sync immediately.
59
+ * **The AI Knowledge Gap**: Generative AI coding assistants, enterprise copilots, and retrieval-augmented generation (RAG) engines require clean, structured, and pre-digested context:
60
+ * **Broken Formula Boundaries**: Naive text splitters slice long DAX expressions and nested M queries mid-clause, destroying semantic integrity and syntax validity during chunking.
61
+ * **Missing Graph & Topology Metadata**: Standard vector indexes lack calculation depth, table-relationship cardinalities, and upstream/downstream lineage needed for hybrid filtering and precise graph retrieval.
62
+ * **Context Window Pollution**: Raw, unfiltered TMDL/TMSL dumps contain redundant visual formatting, display folders, and layout hashes that dilute model attention and waste token budget.
63
+ * **Unstructured Ingestion Burden**: Without an automated compiler producing self-contained semantic markdown units (complete with YAML frontmatter), AI agents must parse and reconstruct relational topology on the fly.
64
+
65
+ **The Mission of `pbip-doc`**: Provide a fast, headless, zero-dependency static analysis engine that reads raw PBIP repositories and compiles their complete semantic architecture into two distinct, high-fidelity formats:
66
+ 1. **For Humans**: A self-contained, offline Zero-JS HTML Enterprise Wiki Portal with collapsible `<details>` sidebar tree navigation, pure-CSS tab switching, embedded interactive vector relationship diagrams (hover-focus), and build-time Light/Dark/Auto theming.
67
+ 2. **For AI Systems**: Atomic, pre-chunked Markdown documentation with structured YAML frontmatter, engineered specifically for vector databases and enterprise RAG retrieval.
68
+
69
+ ---
70
+
71
+ ## ๐Ÿ’ก The Solution: How `pbip-doc` Delivers the Mission
72
+
73
+ Instead of connecting to a live Analysis Services database or launching external rendering processes, `pbip-doc` performs **direct static analysis** on source files in the file system.
74
+
75
+ ```text
76
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
77
+ โ”‚ PBIP / Fabric Source โ”‚
78
+ โ”‚ - TMDL / TMSL Semantic Models โ”‚
79
+ โ”‚ - PBIR / Legacy Reports โ”‚
80
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
81
+ โ”‚
82
+ โ–ผ
83
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
84
+ โ”‚ Static Analysis Engine โ”‚ โ—„โ”€โ”€ Pure Python Standard Library
85
+ โ”‚ - Power Query M Lineage โ”‚ (Zero runtime dependencies)
86
+ โ”‚ - Star/Snowflake Classifier โ”‚
87
+ โ”‚ - DAX DAG & Depth Resolver โ”‚
88
+ โ”‚ - Visual Canvas Geometry โ”‚
89
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
90
+ โ”‚
91
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
92
+ โ–ผ โ–ผ
93
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
94
+ โ”‚ For Humans โ”‚ โ”‚ For AI โ”‚
95
+ โ”‚ Offline HTMLโ”‚ โ”‚ RAG-Ready โ”‚
96
+ โ”‚ Wiki Portal โ”‚ โ”‚ Markdown โ”‚
97
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
98
+ ```
99
+
100
+ ### Key Architectural Pillars
101
+
102
+ * **Zero External Dependencies**: Implemented entirely with the Python Standard Library (`re`, `json`, `pathlib`, `dataclasses`, `argparse`, `math`, `html`, `base64`). It runs in restricted, air-gapped corporate environments without `pip install` supply-chain risks.
103
+ * **Multi-Artifact Workspace Discovery**: Recursively detects all semantic models and reports across a repository, building a consolidated catalog with directory hierarchies and composite model mapping.
104
+ * **End-to-End M Lineage Resolution**: Parses Power Query M syntax (`let...in`, item access, custom functions) to trace data flows from physical storage endpoints (SQL Server, Lakehouse, SharePoint, OData, Web) through intermediate staging queries down to model tables.
105
+ * **Automated Topology & DAX DAG**: Automatically identifies Fact, Dimension, Snowflake Outrigger, and Bridge tables, while calculating directed acyclic graphs (DAGs) for DAX measures to determine calculation depth and downstream impact.
106
+ * **Pure Vector SVG Architecture**: Generates interactive Star/Snowflake relationship diagrams and visual mini-maps entirely in standard vector SVG, avoiding external renderers (Graphviz, Mermaid, Canvas) or JavaScript execution.
107
+ * **Zero-JS Offline Safety**: The generated HTML portal uses pure HTML5 & CSS (`<details>` collapsible sidebar tree, `:checked` tab switching, CSS grid/flexbox, and `prefers-color-scheme: dark` support in `auto` theme mode alongside build-time `--theme auto|light|dark`). It functions over the local `file://` protocol without JavaScript, hosting requirements, or browser security warnings.
108
+
109
+ ---
110
+
111
+ ## ๐Ÿš€ Installation & Quickstart
112
+
113
+ ### Installation
114
+
115
+ `pbip-doc` supports standard Python packaging as well as direct execution without installation:
116
+
117
+ ```bash
118
+ # Option A: Install directly from GitHub (recommended before PyPI release)
119
+ # Exposes the `pbip-doc` command directly in your PATH
120
+ pip install git+https://github.com/mazzolenifsimone/pbip-doc.git
121
+
122
+ # Or clone and install in editable mode locally:
123
+ git clone https://github.com/mazzolenifsimone/pbip-doc.git
124
+ cd pbip-doc
125
+ pip install -e .
126
+
127
+ # Option B: Clone and run directly without installing (Zero setup)
128
+ git clone https://github.com/mazzolenifsimone/pbip-doc.git
129
+ cd pbip-doc
130
+ python -m pbip_doc --help
131
+ ```
132
+
133
+ > [!NOTE]
134
+ > Once published on PyPI, standard installation via `pip install pbip-doc` will also be available.
135
+
136
+ ---
137
+
138
+ ### Core Usage Examples
139
+
140
+ > [!TIP]
141
+ > **Try it immediately on the bundled sample:**
142
+ > ```bash
143
+ > pbip-doc docgen samples/Ecommerce_Sales -o ./docs -f both
144
+ > # Or running without installing:
145
+ > python -m pbip_doc docgen samples/Ecommerce_Sales -o ./docs -f both
146
+ > ```
147
+
148
+ #### 1. Document a Single Model or Workspace
149
+ Generate both the HTML Enterprise Wiki Portal and the AI RAG-ready Markdown docs:
150
+
151
+ ```bash
152
+ # Generate both formats in ./docs
153
+ pbip-doc docgen path/to/model_or_workspace -o ./docs -f both
154
+ ```
155
+
156
+ *(If running from a git clone without installing, simply use `python -m pbip_doc docgen ...`)*
157
+
158
+ #### 2. Generate Only the Offline HTML Wiki Portal
159
+ ```bash
160
+ pbip-doc docgen path/to/model_or_workspace -o ./docs -f html
161
+ ```
162
+
163
+ For direct hosting on Microsoft SharePoint Online or Microsoft Teams Document Libraries:
164
+ ```bash
165
+ # Generate documentation with .aspx extension for direct SharePoint Online browsing
166
+ pbip-doc docgen path/to/model -o ./sharepoint_docs --html-extension aspx
167
+ ```
168
+
169
+ #### 3. Generate Only Markdown for AI RAG Ingestion
170
+ ```bash
171
+ pbip-doc docgen path/to/model_or_workspace -o ./kb_docs -f markdown
172
+ ```
173
+
174
+ #### 4. Quick Terminal Inspection
175
+ Inspect model architecture and DAX depths directly in the console without writing files:
176
+
177
+ ```bash
178
+ pbip-doc inspect path/to/model
179
+ ```
180
+
181
+ ---
182
+
183
+ ## ๐Ÿ“‚ Output Structure & AI Knowledge Base Format
184
+
185
+ When compiled with `-f both`, `pbip-doc` organizes generated documentation into clean, isolated directories based on execution mode:
186
+
187
+ ### Workspace Mode (Multi-Model / Multi-Report or `--workspace`)
188
+ Used when pointing `docgen` to a directory containing multiple PBIP models/reports, or when forcing `--workspace`:
189
+
190
+ ```text
191
+ docs/
192
+ โ”œโ”€โ”€ html/ โ—„โ”€โ”€ Human Documentation (Open in any browser)
193
+ โ”‚ โ”œโ”€โ”€ index.html โ”‚ Master workspace catalog & global lineage
194
+ โ”‚ โ”œโ”€โ”€ assets/style.css โ”‚ Standalone CSS (Zero external network calls)
195
+ โ”‚ โ”œโ”€โ”€ models/<ModelName>/ โ”‚ Model overview (index.html), tables/, measures/, functions/, etl/, diagrams/
196
+ โ”‚ โ””โ”€โ”€ reports/<ReportName>/ โ”‚ Report overview (index.html) & visuals/ (canvas layouts, SVG mini-maps)
197
+ โ”‚
198
+ โ””โ”€โ”€ markdown/ โ—„โ”€โ”€ AI Knowledge Base (Ingest into Vector DB / LLM)
199
+ โ”œโ”€โ”€ README.md โ”‚ Master repository index & dependency matrix
200
+ โ”œโ”€โ”€ models/<ModelName>/ โ”‚ Atomic pages per model
201
+ โ”‚ โ”œโ”€โ”€ README.md โ”‚ Model catalog & architecture overview
202
+ โ”‚ โ”œโ”€โ”€ tables/*.md โ”‚ Data dictionaries and column origins
203
+ โ”‚ โ”œโ”€โ”€ measures/**/*.md โ”‚ DAX formulas with calculation depth metadata
204
+ โ”‚ โ”œโ”€โ”€ functions/*.md โ”‚ DAX User-Defined Functions (UDFs) & parameter specs
205
+ โ”‚ โ”œโ”€โ”€ etl/*.md โ”‚ Power Query M code and staging lineage
206
+ โ”‚ โ””โ”€โ”€ diagrams/*.svg โ”‚ Star/Snowflake & focal relationship SVG diagrams
207
+ โ””โ”€โ”€ reports/<ReportName>/ โ”‚ Report overview (README.md) & visuals/*.md (visuals/assets/*.svg)
208
+ ```
209
+
210
+ ### Single-Model Mode (Standalone Model / PBIP Solution)
211
+ Used when executing `docgen` on a single semantic model or individual PBIP solution folder without `--workspace`:
212
+
213
+ ```text
214
+ docs/
215
+ โ”œโ”€โ”€ html/ โ—„โ”€โ”€ Human Documentation (Open in any browser)
216
+ โ”‚ โ”œโ”€โ”€ index.html โ”‚ Model dashboard & interactive navigation
217
+ โ”‚ โ”œโ”€โ”€ assets/style.css โ”‚ Standalone CSS (Zero external network calls)
218
+ โ”‚ โ”œโ”€โ”€ tables/*.html โ”‚ Individual table data dictionaries
219
+ โ”‚ โ”œโ”€โ”€ measures/**/*.html โ”‚ DAX measures with dependency cards & visual callouts
220
+ โ”‚ โ”œโ”€โ”€ functions/*.html โ”‚ DAX User-Defined Functions (UDFs) & parameter specs
221
+ โ”‚ โ”œโ”€โ”€ etl/*.html โ”‚ Power Query M lineage & expression documentation
222
+ โ”‚ โ”œโ”€โ”€ diagrams/*.svg โ”‚ Star/Snowflake & focal relationship SVG diagrams
223
+ โ”‚ โ””โ”€โ”€ visuals/ โ”‚ Associated report pages & visuals/assets/*.svg (if present)
224
+ โ”‚
225
+ โ””โ”€โ”€ markdown/ โ—„โ”€โ”€ AI Knowledge Base (Ingest into Vector DB / LLM)
226
+ โ”œโ”€โ”€ <ModelName>.md โ”‚ Model overview with architecture & metrics
227
+ โ”œโ”€โ”€ tables/*.md โ”‚ Table schemas and column metadata
228
+ โ”œโ”€โ”€ measures/**/*.md โ”‚ DAX formulas with calculation depth metadata
229
+ โ”œโ”€โ”€ functions/*.md โ”‚ DAX User-Defined Functions (UDFs) & parameter specs
230
+ โ”œโ”€โ”€ etl/*.md โ”‚ Power Query M scripts & upstream dependencies
231
+ โ”œโ”€โ”€ diagrams/*.svg โ”‚ Star/Snowflake & focal relationship SVG diagrams
232
+ โ””โ”€โ”€ visuals/ โ”‚ Report pages (*.md) & SVG mini-maps in assets/ (if present)
233
+ ```
234
+
235
+ ### Sample Machine-Readable YAML Frontmatter (Measure)
236
+
237
+ YAML frontmatter is **enabled by default in generated Markdown files** (can be omitted with `--no-frontmatter`) and is **not included in HTML files**. This allows vector chunkers (Azure AI Search, Pinecone, Qdrant, Chroma) to index semantic attributes as metadata filters:
238
+
239
+ ```yaml
240
+ ---
241
+ title: "Measure: [Net Profit Margin]"
242
+ pbip_project: Ecommerce_Sales
243
+ entity_name: Net Profit Margin
244
+ doc_type: dax_measure
245
+ table_name: Orders
246
+ calculation_depth: 2
247
+ is_base_measure: false
248
+ direct_dependencies: [Total Revenue, Total Cost]
249
+ all_upstream_dependencies: [Total Revenue, Total Cost]
250
+ downstream_measures_count: 1
251
+ downstream_measures: [Regional Performance Index]
252
+ referenced_tables: [Orders]
253
+ referenced_columns:
254
+ - "Orders[GrossAmount]"
255
+ - "Orders[TaxRate]"
256
+ tags:
257
+ - semantic_model
258
+ - dax_measure
259
+ - depth_2
260
+ - Orders
261
+ - Net_Profit_Margin
262
+ - Ecommerce_Sales
263
+ - composite_measure
264
+ ---
265
+ # Measure: `[Net Profit Margin]`
266
+ ...
267
+ ```
268
+
269
+ ---
270
+
271
+ ## ๐Ÿ“‹ Comprehensive CLI Reference
272
+
273
+ The `pbip-doc` command-line interface provides dedicated subcommands for documentation generation, metadata extraction, inspection, and configuration.
274
+
275
+ ### Available Subcommands
276
+
277
+ Command | Description
278
+ :--- | :---
279
+ `docgen` | Generates modular Markdown and/or the HTML Enterprise Wiki Portal.
280
+ `extract` (alias: `parse`) | Parses a semantic model and exports a normalized, single-source-of-truth JSON metadata model.
281
+ `inspect` (alias: `scan`) | Outputs a detailed ASCII summary of model topology, data sources, and DAX DAG depths in the terminal.
282
+ `report-extract` | Parses a PBIP `*.Report` folder and exports its visual catalog as JSON.
283
+ `report-inspect` | Prints a summary of report pages, visuals, spatial zones, and calculation contexts.
284
+ `config` | Displays current defaults (`--show`) or initializes a custom `pbip_doc.config.json` (`--init`).
285
+
286
+ ---
287
+
288
+ ### Detailed `docgen` Command Options
289
+
290
+ Below is the complete reference of parameters supported by `pbip-doc docgen <path>`:
291
+
292
+ #### 1. Core & Output Parameters
293
+ Flag | Type / Choices | Default | Description
294
+ :--- | :---: | :---: | :---
295
+ `-o, --output-dir` | Path | `docs/` | Destination directory for generated documentation files.
296
+ `-f, --format` | `markdown` \| `html` \| `both` | `html` | Output format to generate.
297
+ `--html-extension` | String | `html` | File extension for HTML pages (e.g. `html`, `aspx` for SharePoint Online browsing compatibility, or any custom extension).
298
+ `--project-name` | String | *Auto-detected* | Custom project name override for frontmatter metadata and headers.
299
+ `--workspace` | Flag | *Auto-detected* | Explicitly forces multi-artifact workspace catalog layout.
300
+
301
+ #### 2. Scope & Inclusion Filters
302
+ Flag | Type / Choices | Default | Description
303
+ :--- | :---: | :---: | :---
304
+ `--no-model, --no-models` | Flag | `False` | Excludes semantic model documentation (tables, measures, functions, model overview).
305
+ `--no-report, --no-reports` | Flag | `False` | Excludes report presentation documentation (pages, visuals, report overview).
306
+ `--no-dataflow, --no-dataflows` | Flag | `False` | Excludes Power Query ETL documentation (shared queries, expressions, dataflow overview).
307
+ `--no-visuals` | Flag | `False` | Excludes visual-level page documentation.
308
+ `--no-visual-svg-maps`| Flag | `False` | Disables rendering of scaled visual SVG layout mini-maps.
309
+ `--no-frontmatter` | Flag | `False` | Omits YAML frontmatter at the top of markdown documents.
310
+ `--no-m-code` | Flag | `False` | Omits raw Power Query M code snippets from table documents.
311
+ `--include-auto-tables`| Flag | `False` | Includes Power BI internal auto-generated date/time tables.
312
+ `--include-inherited-entities`| Flag | `False` | Generates dedicated pages for inherited entities and remote measures.
313
+ `--exclude-tables` | Comma-separated | `None` | Comma-delimited list of table names to exclude from documentation.
314
+
315
+ #### 3. Styling, Branding & Visualization
316
+ Flag | Type / Choices | Default | Description
317
+ :--- | :---: | :---: | :---
318
+ `--theme` | `auto` \| `light` \| `dark` | `auto` | Color theme for the HTML portal (`auto` respects OS `prefers-color-scheme: dark`).
319
+ `--html-title` | String | *Auto-detected* | Custom title text displayed in the HTML portal header.
320
+ `--sidebar-icon` | Preset \| Path \| Inline SVG / Data-URI | `default` | Custom icon for HTML sidebar header: `'default'` (`pbip_doc_logo_large.svg`), presets (`pbip_doc_logo`, `cube`, `database`, `barchart`, `fabric`, `catalog`), path to `.svg`/`.png`, inline `<svg>`/`<img>`, or `Data-URI`.
321
+ `--no-diagrams, --no-relationship-diagrams` | Flag | `False` | Disables generation of SVG topological relationship diagrams.
322
+ `--workspace-grouping`| `folder` \| `flat` | `folder` | Catalog organization: `folder` (by directory) or `flat` (by artifact type).
323
+ `--workspace-folder-depth`| Integer | `1` | Subdirectory depth level when `workspace-grouping` is set to `folder`.
324
+
325
+ #### 4. Custom Paths & Remote Linking
326
+ Flag | Type / Choices | Default | Description
327
+ :--- | :---: | :---: | :---
328
+ `--tables-dir` | String | `tables` | Subdirectory name for table documentation.
329
+ `--measures-dir` | String | `measures` | Subdirectory name for measure documentation.
330
+ `--functions-dir` | String | `functions` | Subdirectory name for DAX UDF documentation.
331
+ `--visuals-dir` | String | `visuals` | Subdirectory name for report page documentation.
332
+ `--report-path` | Path | `None` | Explicit path to an associated `*.Report` folder or `report.json`.
333
+ `--report-dataset-name` | String | `None` | Override target semantic model name for report visual links when bound to an external dataset.
334
+ `--base-doc-url, --base-doc-path` | URL / Path | `None` | Base URL or path used to prefix internal documentation hyperlinks.
335
+ `--external-docs-base-url, --external-docs-base-path`| URL / Path | `None` | Base URL or path for cross-linking remote/external semantic models.
336
+ `--external-doc-path NAME=URL`| String (Repeated) | `None` | Explicit URL or directory path for a specific upstream external model (overrides `--external-docs-base-url`).
337
+
338
+ #### 5. Configuration File & Overrides
339
+ Flag | Type / Choices | Default | Description
340
+ :--- | :---: | :---: | :---
341
+ `-c, --config` | Path | `None` | Path to a custom `pbip_doc.config.json` configuration file.
342
+ `--layout-config` | Path | `None` | Path to a custom 3-level section layout JSON file.
343
+ `--dump-default-layout`| File Path | `None` | Exports default layout configuration JSON to stdout or file and exits.
344
+ `--set KEY=VALUE` | Key=Value | `None` | Directly overrides any configuration setting (can be repeated).
345
+ `--print-config` | Flag | `False` | Prints the resolved configuration to stdout before execution.
346
+
347
+ ---
348
+
349
+ ## โš™๏ธ Configuration File Example (`pbip_doc.config.json`)
350
+
351
+ To standardize settings across your team or CI/CD pipelines, place a `pbip_doc.config.json` file in your repository root or target directory (run `pbip-doc config --show` to inspect all supported keys):
352
+
353
+ ```json
354
+ {
355
+ "project_name": "Sales & Revenue Platform",
356
+ "output_format": "both",
357
+ "html_extension": "html",
358
+ "html_theme": "auto",
359
+ "sidebar_icon": "fabric",
360
+ "exclude_auto_date_tables": true,
361
+ "include_relationship_diagrams": true,
362
+ "workspace_grouping": "folder",
363
+ "workspace_folder_depth": 1,
364
+ "excluded_tables": ["_DevScratch", "TempStaging"]
365
+ }
366
+ ```
367
+
368
+ > [!TIP]
369
+ > Setting `"html_extension": "aspx"` enables native in-browser rendering when hosting generated documentation inside Microsoft SharePoint Online or Microsoft Teams Document Libraries.
370
+
371
+ ---
372
+
373
+ ## ๐Ÿ—๏ธ Technical Architecture & Internal Design
374
+
375
+ For detailed documentation on the internal engine architecture (Lexer/Parser implementations, AST data structures, Lineage Graph algorithms, and contribution standards), please consult [`ARCHITECTURE.md`](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/ARCHITECTURE.md).
376
+
377
+ ---
378
+
379
+ ## ๐Ÿงช Testing
380
+
381
+ The test suite runs entirely on the standard Python `unittest` framework:
382
+
383
+ ```bash
384
+ # Run all unit tests
385
+ python -m unittest discover tests -v
386
+ ```
387
+
388
+ ---
389
+
390
+ ## ๐Ÿ“„ License
391
+
392
+ This project is licensed under the [MIT License](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/LICENSE).