diff --git a/README.md b/README.md index 7d0924b..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,84 +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) - -# 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' - ) - -# 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" -) - -# Save docs to the default location -docs.save_documentation() -``` ### Use Cases @@ -328,5 +249,90 @@ tables = model.Tables[TABLE_NAME].related() tables.refresh() ``` +## 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. +# 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_translations( + 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 > 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. +```python +import pytabular + +# Connect to a Tabular Model Model +model = pytabular.Tabular(CONNECTION_STR) + +# Initiate the Docs and set a friendly name to store the markdown files. +docs = pytabular.ModelDocumenter( + model = model, + friendly_name = "Adventure Works" +) + +# Generate the pages. +docs.generate_documentation_pages() + +# Save docs to the default location +docs.save_documentation() +``` + ### Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) \ No newline at end of file +See [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/pytabular/document.py b/pytabular/document.py index 332276d..903e71f 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