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.
- pbip_doc-0.2.0/LICENSE +21 -0
- pbip_doc-0.2.0/PKG-INFO +392 -0
- pbip_doc-0.2.0/README.md +360 -0
- pbip_doc-0.2.0/pbip_doc/__init__.py +54 -0
- pbip_doc-0.2.0/pbip_doc/__main__.py +7 -0
- pbip_doc-0.2.0/pbip_doc/cli.py +804 -0
- pbip_doc-0.2.0/pbip_doc/codebase_scanner.py +955 -0
- pbip_doc-0.2.0/pbip_doc/dax_formatter.py +596 -0
- pbip_doc-0.2.0/pbip_doc/docgen/__init__.py +59 -0
- pbip_doc-0.2.0/pbip_doc/docgen/config.py +979 -0
- pbip_doc-0.2.0/pbip_doc/docgen/engine.py +349 -0
- pbip_doc-0.2.0/pbip_doc/docgen/expression_doc.py +912 -0
- pbip_doc-0.2.0/pbip_doc/docgen/function_doc.py +435 -0
- pbip_doc-0.2.0/pbip_doc/docgen/html_assets.py +1770 -0
- pbip_doc-0.2.0/pbip_doc/docgen/html_builders.py +4694 -0
- pbip_doc-0.2.0/pbip_doc/docgen/html_engine.py +505 -0
- pbip_doc-0.2.0/pbip_doc/docgen/html_layout.py +522 -0
- pbip_doc-0.2.0/pbip_doc/docgen/index_doc.py +1055 -0
- pbip_doc-0.2.0/pbip_doc/docgen/layout_engine.py +748 -0
- pbip_doc-0.2.0/pbip_doc/docgen/link_resolver.py +352 -0
- pbip_doc-0.2.0/pbip_doc/docgen/measure_doc.py +498 -0
- pbip_doc-0.2.0/pbip_doc/docgen/relationship_config.py +211 -0
- pbip_doc-0.2.0/pbip_doc/docgen/relationship_diagram.py +2062 -0
- pbip_doc-0.2.0/pbip_doc/docgen/section_engine.py +134 -0
- pbip_doc-0.2.0/pbip_doc/docgen/table_doc.py +1350 -0
- pbip_doc-0.2.0/pbip_doc/docgen/utils.py +531 -0
- pbip_doc-0.2.0/pbip_doc/docgen/visual_doc.py +691 -0
- pbip_doc-0.2.0/pbip_doc/docgen/workspace_engine.py +1926 -0
- pbip_doc-0.2.0/pbip_doc/m_formatter.py +269 -0
- pbip_doc-0.2.0/pbip_doc/m_lineage.py +549 -0
- pbip_doc-0.2.0/pbip_doc/m_parser.py +1142 -0
- pbip_doc-0.2.0/pbip_doc/m_step_graph.py +881 -0
- pbip_doc-0.2.0/pbip_doc/m_table_parser.py +353 -0
- pbip_doc-0.2.0/pbip_doc/measure_analyzer.py +261 -0
- pbip_doc-0.2.0/pbip_doc/model_schema.py +637 -0
- pbip_doc-0.2.0/pbip_doc/parser.py +1383 -0
- pbip_doc-0.2.0/pbip_doc/report_parser.py +1711 -0
- pbip_doc-0.2.0/pbip_doc/report_schema.py +215 -0
- pbip_doc-0.2.0/pbip_doc/star_schema.py +601 -0
- pbip_doc-0.2.0/pbip_doc/tmdl_lexer.py +469 -0
- pbip_doc-0.2.0/pbip_doc.egg-info/PKG-INFO +392 -0
- pbip_doc-0.2.0/pbip_doc.egg-info/SOURCES.txt +61 -0
- pbip_doc-0.2.0/pbip_doc.egg-info/dependency_links.txt +1 -0
- pbip_doc-0.2.0/pbip_doc.egg-info/entry_points.txt +4 -0
- pbip_doc-0.2.0/pbip_doc.egg-info/top_level.txt +1 -0
- pbip_doc-0.2.0/pyproject.toml +52 -0
- pbip_doc-0.2.0/setup.cfg +4 -0
- pbip_doc-0.2.0/tests/test_cli.py +121 -0
- pbip_doc-0.2.0/tests/test_codebase_scanner.py +126 -0
- pbip_doc-0.2.0/tests/test_composite_and_lineage_fixes.py +1562 -0
- pbip_doc-0.2.0/tests/test_dax_formatter.py +114 -0
- pbip_doc-0.2.0/tests/test_html_docgen.py +1706 -0
- pbip_doc-0.2.0/tests/test_layout_engine.py +412 -0
- pbip_doc-0.2.0/tests/test_link_resolver.py +145 -0
- pbip_doc-0.2.0/tests/test_m_lineage.py +217 -0
- pbip_doc-0.2.0/tests/test_m_parser.py +264 -0
- pbip_doc-0.2.0/tests/test_m_step_graph.py +197 -0
- pbip_doc-0.2.0/tests/test_pbip_doc.py +3603 -0
- pbip_doc-0.2.0/tests/test_refinements.py +354 -0
- pbip_doc-0.2.0/tests/test_relationship_diagram.py +745 -0
- pbip_doc-0.2.0/tests/test_report_parser.py +1664 -0
- pbip_doc-0.2.0/tests/test_tmdl_lexer.py +189 -0
- 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.
|
pbip_doc-0.2.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://www.python.org/)
|
|
38
|
+
[](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/LICENSE)
|
|
39
|
+
[-brightgreen.svg)]()
|
|
40
|
+
[]()
|
|
41
|
+
[]()
|
|
42
|
+
[](https://github.com/mazzolenifsimone/pbip-doc/blob/v0.2.0/ARCHITECTURE.md)
|
|
43
|
+
|
|
44
|
+

|
|
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).
|