From 8db90b07b697ab84a22bf876cab6455e31db24ea Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Tue, 31 Jan 2023 17:04:06 +0100 Subject: [PATCH 01/10] Update README.md --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 63d0a2e..3afd8fa 100644 --- a/README.md +++ b/README.md @@ -248,5 +248,18 @@ tables = model.Tables[TABLE_NAME].Related() tables.Refresh() ``` +## Documenting a Model + +Args: +- Docs Location: +- Friendly Name: + +### Refreshing a Power BI Premium Model + +### Refreshing a Analysis Server Model + +### Refreshing a Power BI > Local Model. +- The Local model doesn't have a name, only an Id. So we need to Supply a "Friendly Name". + ### Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) \ No newline at end of file +See [CONTRIBUTING.md](CONTRIBUTING.md) From e82f137859d7ad0d1cbf6be21c36a547921c3a9d Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Tue, 7 Feb 2023 21:47:54 +0100 Subject: [PATCH 02/10] Update README.md --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3afd8fa..7d5dc92 100644 --- a/README.md +++ b/README.md @@ -251,15 +251,54 @@ tables.Refresh() ## Documenting a Model Args: -- Docs Location: -- Friendly Name: +```python +model: Tabular, +friendly_name: str = str(), +save_location: str = "docs", +general_page_url: str = "1-general-information.md", +measure_page_url: str = "2-measures.md", +table_page_url: str = "3-tables.md", +column_page_url: str = "4-columns.md", +roles_page_url: str = "5-roles.md", +``` + +### Documenting a Power BI Premium Model +```python +import pytabular +import logging -### Refreshing a Power BI Premium Model +logger = logging.getLogger("PyTabular") +model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") -### Refreshing a Analysis Server Model +docs = pytabular.ModelDocumenter(model) +docs.set_transalation(True, 'en-US') +docs.save_documentation() +``` + +### Documenting a Analysis Server Model +```python +import pytabular -### Refreshing a Power BI > Local Model. +# Connect to the Analysis Server Model +model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") + +# Initiate the Docs +docs = pytabular.ModelDocumenter(model) + +# Save docs to the default location +docs.save_documentation() +``` +### Documenting a Power BI > Local Model. - The Local model doesn't have a name, only an Id. So we need to Supply a "Friendly Name". +```python +import pytabular +import logging + +logger = logging.getLogger("PyTabular") +model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") +docs = pytabular.ModelDocumenter(model) +docs.save_documentation() +``` ### Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) From b9f83594b14e5333612014887b833df7ae97df66 Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Tue, 7 Feb 2023 22:00:53 +0100 Subject: [PATCH 03/10] Update README.md --- README.md | 66 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 7d5dc92..145a5fa 100644 --- a/README.md +++ b/README.md @@ -249,55 +249,81 @@ tables.Refresh() ``` ## Documenting a Model - +The Tabular model co Args: -```python -model: Tabular, -friendly_name: str = str(), -save_location: str = "docs", -general_page_url: str = "1-general-information.md", -measure_page_url: str = "2-measures.md", -table_page_url: str = "3-tables.md", -column_page_url: str = "4-columns.md", -roles_page_url: str = "5-roles.md", -``` +- **model**: Tabular, +- **friendly_name**: str = str(), + +To specify the location of the docs, just supply the save location with a new folder name argument. +- **save_location**: str = "docs", + +Each page in the generation process has it's own specific name, with these arguments you can rename them to your liking. +- **general_page_url**: str = "1-general-information.md", +- **measure_page_url**: str = "2-measures.md", +- **table_page_url**: str = "3-tables.md", +- **column_page_url**: str = "4-columns.md", +- **roles_page_url**: str = "5-roles.md", + +### Documenting a Model +The simpelst way to document a tabular model is to connect to the model, and initialize the documentation and execute `save_documentation()`. -### Documenting a Power BI Premium Model ```python import pytabular -import logging -logger = logging.getLogger("PyTabular") +# Connect to a Tabular Model Model model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") +# Initiate the Docs docs = pytabular.ModelDocumenter(model) -docs.set_transalation(True, 'en-US') + +# Save docs to the default location docs.save_documentation() ``` -### Documenting a Analysis Server Model + +### Documenting a Model with Cultures +Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'). + ```python import pytabular -# Connect to the Analysis Server Model +# Connect to a Tabular Model Model model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") # Initiate the Docs docs = pytabular.ModelDocumenter(model) +# Set the translation for documentation to an available culture. +docs = pytabular.ModelDocumenter(model) + +# By setting the Tranlsations to `True` it will check if it exists and if it does, +# it will start using the translations for the docs +docs.set_transalation( + enable_translations=True, + culture = 'en-US' + ) + # Save docs to the default location docs.save_documentation() ``` ### Documenting a Power BI > Local Model. -- The Local model doesn't have a name, only an Id. So we need to Supply a "Friendly Name". +The Local model doesn't have a name, only an Id. So we need to Supply a "Friendly Name", which will be used to store the markdown files. ```python import pytabular -import logging -logger = logging.getLogger("PyTabular") +# Connect to a Tabular Model Model model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") +# Initiate the Docs docs = pytabular.ModelDocumenter(model) + +# Set the translation for documentation to an available culture. +docs = pytabular.ModelDocumenter( + model = model, + friendly_name = "Adventure Works" +) + +# Save docs to the default location docs.save_documentation() ``` ### Contributing From adb0541ee37d3d1ecb539c3f7301e7af64bffbcd Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Tue, 7 Feb 2023 22:10:13 +0100 Subject: [PATCH 04/10] Update README.md --- README.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 145a5fa..9ef741b 100644 --- a/README.md +++ b/README.md @@ -249,20 +249,23 @@ tables.Refresh() ``` ## Documenting a Model -The Tabular model co +The Tabular model contains a lot of information that can be used to generation documentation if filled in. Currently the markdown files are generated with the Docusaurs heading in place, but this will be changed in future to support multiple documentation platforms. + +**Tip**: With Tabular Editor 2 (Free) or 3 (Paid) you can easily add Descriptioms, Translations (Cultures) and other additonal information that can later be used for generating the documentation. + Args: -- **model**: Tabular, -- **friendly_name**: str = str(), +- **model**: Tabular +- **friendly_name**: Default > No Value To specify the location of the docs, just supply the save location with a new folder name argument. -- **save_location**: str = "docs", +- **save_location**: Default > docs Each page in the generation process has it's own specific name, with these arguments you can rename them to your liking. -- **general_page_url**: str = "1-general-information.md", -- **measure_page_url**: str = "2-measures.md", -- **table_page_url**: str = "3-tables.md", -- **column_page_url**: str = "4-columns.md", -- **roles_page_url**: str = "5-roles.md", +- **general_page_url**: Default > 1-general-information.md +- **measure_page_url**: Default > 2-measures.md +- **table_page_url**: Default > 3-tables.md +- **column_page_url**: Default > 4-columns.md +- **roles_page_url**: Default > 5-roles.md ### Documenting a Model The simpelst way to document a tabular model is to connect to the model, and initialize the documentation and execute `save_documentation()`. @@ -271,7 +274,7 @@ The simpelst way to document a tabular model is to connect to the model, and ini import pytabular # Connect to a Tabular Model Model -model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") +model = pytabular.Tabular(CONNECTION_STR) # Initiate the Docs docs = pytabular.ModelDocumenter(model) @@ -280,7 +283,6 @@ docs = pytabular.ModelDocumenter(model) docs.save_documentation() ``` - ### Documenting a Model with Cultures Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'). @@ -288,7 +290,7 @@ Some model creators choose to add cultures to a tabular model for different kind import pytabular # Connect to a Tabular Model Model -model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") +model = pytabular.Tabular(CONNECTION_STR) # Initiate the Docs docs = pytabular.ModelDocumenter(model) @@ -307,17 +309,14 @@ docs.set_transalation( docs.save_documentation() ``` ### Documenting a Power BI > Local Model. -The Local model doesn't have a name, only an Id. So we need to Supply a "Friendly Name", which will be used to store the markdown files. +The Local model doesn't have a "name", only an Id. So we need to Supply a "Friendly Name", which will be used to store the markdown files. ```python import pytabular # Connect to a Tabular Model Model -model = pytabular.Tabular(f"{SERVER};Catalog={INITIAL_CATALOG}") - -# Initiate the Docs -docs = pytabular.ModelDocumenter(model) +model = pytabular.Tabular(CONNECTION_STR) -# Set the translation for documentation to an available culture. +# Initiate the Docs and set a friendly name to store the markdown files. docs = pytabular.ModelDocumenter( model = model, friendly_name = "Adventure Works" From 238da72b9eb7c48dd21955d12cfd9594b3a49377 Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:09:03 +0100 Subject: [PATCH 05/10] Update document.py --- pytabular/document.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pytabular/document.py b/pytabular/document.py index 332276d..6ce6f97 100644 --- a/pytabular/document.py +++ b/pytabular/document.py @@ -54,6 +54,7 @@ def __init__( self.table_page: str = str() self.column_page: str = str() self.roles_page: str = str() + self.category_page: str = str() self.category_file_name: str = "_category_.yml" self.general_page_url: str = general_page_url From fd37dbc32f8852ee5e24a2c0092cb732329893bf Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:18:21 +0100 Subject: [PATCH 06/10] Update README.md --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2befd34..d3f81c1 100644 --- a/README.md +++ b/README.md @@ -359,6 +359,9 @@ model = pytabular.Tabular(CONNECTION_STR) # Initiate the Docs docs = pytabular.ModelDocumenter(model) +# Generate the pages. +docs.generate_documentation_pages() + # Save docs to the default location docs.save_documentation() ``` @@ -376,15 +379,16 @@ model = pytabular.Tabular(CONNECTION_STR) docs = pytabular.ModelDocumenter(model) # Set the translation for documentation to an available culture. -docs = pytabular.ModelDocumenter(model) - # By setting the Tranlsations to `True` it will check if it exists and if it does, # it will start using the translations for the docs -docs.set_transalation( - enable_translations=True, +docs.set_translations( + enable_translations = True, culture = 'en-US' ) +# Generate the pages. +docs.generate_documentation_pages() + # Save docs to the default location docs.save_documentation() ``` @@ -402,6 +406,9 @@ docs = pytabular.ModelDocumenter( friendly_name = "Adventure Works" ) +# Generate the pages. +docs.generate_documentation_pages() + # Save docs to the default location docs.save_documentation() ``` From 6e140ce113b210f948d6620b6a8a6f9efaf92886 Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:20:14 +0100 Subject: [PATCH 07/10] Update document.py --- pytabular/document.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pytabular/document.py b/pytabular/document.py index 6ce6f97..903e71f 100644 --- a/pytabular/document.py +++ b/pytabular/document.py @@ -54,7 +54,7 @@ def __init__( self.table_page: str = str() self.column_page: str = str() self.roles_page: str = str() - self.category_page: str = str() + self.category_page: str = str() self.category_file_name: str = "_category_.yml" self.general_page_url: str = general_page_url From b7d014bdfbf18bb7ba72b66628ab10bc17b7afb4 Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:21:08 +0100 Subject: [PATCH 08/10] Update README.md --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index d3f81c1..03abccc 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,9 @@ model = pytabular.Tabular(CONNECTION_STR) # Initiate the Docs docs = pytabular.ModelDocumenter(model) +# Generate the pages. +docs.generate_documentation_pages() + # Save docs to the default location docs.save_documentation() ``` @@ -170,6 +173,9 @@ docs.set_transalation( enable_translations = True, culture = 'en-US' ) + +# Generate the pages. +docs.generate_documentation_pages() # Save docs to the default location docs.save_documentation() @@ -189,6 +195,9 @@ docs = pytabular.ModelDocumenter( save_location = "my-docs-folder" ) +# Generate the pages. +docs.generate_documentation_pages() + # Save docs to the default location docs.save_documentation() ``` From e1e3b6a46c19ed30de01ad94d7170c6bb609d62a Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:24:23 +0100 Subject: [PATCH 09/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 03abccc..ae2f9d0 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ docs.save_documentation() ``` #### Documenting a Model with Cultures -Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'). +Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'`). ```python import pytabular From 74a1dae91cfa9993b9406f57d55a7816a749d5c8 Mon Sep 17 00:00:00 2001 From: Daan Damhuis Date: Fri, 10 Feb 2023 16:27:26 +0100 Subject: [PATCH 10/10] Update README.md --- README.md | 91 ++----------------------------------------------------- 1 file changed, 2 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index ae2f9d0..76869aa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # PyTabular [![PyPI version](https://badge.fury.io/py/python-tabular.svg)](https://badge.fury.io/py/python-tabular) [![Downloads](https://pepy.tech/badge/python-tabular)](https://pepy.tech/project/python-tabular) @@ -114,93 +113,6 @@ model.Tables['Table Name'].Columns['Column Name'].distinct_count() #or model.Tables['Table Name'].Columns['Column Name'].values() ``` -### Documenting a Model -The Tabular model contains a lot of information that can be used to generation documentation if filled in. Currently the markdown files are generated with the Docusaurs heading in place, but this will be changed in future to support multiple documentation platforms. - -**Tip**: With Tabular Editor 2 (Free) or 3 (Paid) you can easily add Descriptioms, Translations (Cultures) and other additonal information that can later be used for generating the documentation. - -#### Args: -- **model**: Tabular -- **friendly_name**: Default > No Value - -To specify the location of the docs, just supply the save location with a new folder name argument. -- **save_location**: Default > docs - -Each page in the generation process has it's own specific name, with these arguments you can rename them to your liking. -- **general_page_url**: Default > 1-general-information.md -- **measure_page_url**: Default > 2-measures.md -- **table_page_url**: Default > 3-tables.md -- **column_page_url**: Default > 4-columns.md -- **roles_page_url**: Default > 5-roles.md - -#### Documenting a Model -The simpelst way to document a tabular model is to connect to the model, and initialize the documentation and execute `save_documentation()`. - -```python -import pytabular - -# Connect to a Tabular Model Model -model = pytabular.Tabular(CONNECTION_STR) - -# Initiate the Docs -docs = pytabular.ModelDocumenter(model) - -# Generate the pages. -docs.generate_documentation_pages() - -# Save docs to the default location -docs.save_documentation() -``` - -#### Documenting a Model with Cultures -Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'`). - -```python -import pytabular - -# Connect to a Tabular Model Model -model = pytabular.Tabular(CONNECTION_STR) - -# Initiate the Docs -docs = pytabular.ModelDocumenter(model) - -# Set the translation for documentation to an available culture. -docs = pytabular.ModelDocumenter(model) - -# By setting the Tranlsations to `True` it will check if it exists and if it does, -# it will start using the translations for the docs -docs.set_transalation( - enable_translations = True, - culture = 'en-US' - ) - -# Generate the pages. -docs.generate_documentation_pages() - -# Save docs to the default location -docs.save_documentation() -``` -#### Documenting a Power BI Desktop Model -The Local model doesn't have a "name", only an Id. So we need to Supply a "Friendly Name", which will be used to store the markdown files. The result of this example with be a folder `my-docs-folder` with a subfolder `Adventure Works` where all the files are stored. -```python -import pytabular - -# Connect to a Tabular Model Model -model = pytabular.Tabular(CONNECTION_STR) - -# Initiate the Docs, set a friendly name to store the markdown files and overwrite the default location. -docs = pytabular.ModelDocumenter( - model = model, - friendly_name = "Adventure Works", - save_location = "my-docs-folder" -) - -# Generate the pages. -docs.generate_documentation_pages() - -# Save docs to the default location -docs.save_documentation() -``` ### Use Cases @@ -376,7 +288,7 @@ docs.save_documentation() ``` ### Documenting a Model with Cultures -Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'). +Some model creators choose to add cultures to a tabular model for different kinds of reasons. We can leverage those cultures to use the translation names instead of the original object names. In order to this you can set translations to `True` and specify the culture you want to use (e.g. `'en-US'`). ```python import pytabular @@ -421,5 +333,6 @@ docs.generate_documentation_pages() # Save docs to the default location docs.save_documentation() ``` + ### Contributing See [CONTRIBUTING.md](CONTRIBUTING.md)