Curts0 / PyTabular

Connect to Tabular Models via Python
https://curts0.github.io/PyTabular/
MIT License
67 stars 11 forks source link

0.3.5 pep8-naming #73

Closed Curts0 closed 1 year ago

Curts0 commented 1 year ago
Curts0 commented 1 year ago

@Daandamhuis can you give this a review when you have time?

I'm trying to correct my lazy naming convention in the past, so I can get #39 closed. I've added pep8-naming to the flake8 github action and got it passing along with all my pytest, which currently sits at about 90% code coverage. Your document.py was already up to the standard, so I didn't have to touch that one.

I'm going to redo the readme and review docstrings before I merge but wanted to get your opinion too.

Daandamhuis commented 1 year ago

@Curts0: I've looked over the changes and they look good. It's better that everything follows the same naming. I saw a variable that ended with _var, which was a bit strange in my opinion. But I can't find it anymore. πŸ˜…

It will break some code for the users, but this will help and most of the code is pretty easily fixable. It's not that you changed the whole naming.

Curts0 commented 1 year ago

@Daandamhuis Okay awesome and thanks for looking. I agree. I'd rather break the code now than later on. I'll hopefully get this in by end of week.

Daandamhuis commented 1 year ago

Yes, definitely. Take the pain now and hopefully it won't impact a lot of people directly.

Daandamhuis commented 1 year ago

@Curts0 : Can you add this to the README.md at the end? Otherwise I’ll create a PR if it’s not easy?

β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”

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:

To specify the location of the docs, just supply the save location with a new folder name argument.

Each page in the generation process has it's own specific name, with these arguments you can rename them to your liking.

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

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

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.

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

Contributing

See CONTRIBUTING.md