Curts0 / PyTabular

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

[Feature] Add Documentation function for model in Docusaurus style #70

Closed Daandamhuis closed 1 year ago

Daandamhuis commented 1 year ago

So this is the basic implementation of the generation of documentation markdown files. These files will be saved in the docs folder, but it can be changed when initializing the "docs".

Wishlist:

@Curts0: Can you look it over, and see what you think?

import pytabular

server = '<Server Address>'
catalog = '<Model Name>'

model = pytabular.Tabular(f"{server};Catalog={catalog}")

docs = pytabular.ModelDocumenter(model=model)
docs.set_translations(enable_translations=True, culture="en-US")
docs.generate_documentation_pages()
docs.save_documentation()
Daandamhuis commented 1 year ago

Table Page Example: image

Measure Page Example: image

Column Page Example

image image

Curts0 commented 1 year ago

Hey @Daandamhuis,

This is going to be a really neat feature to have in PyTabular. I'm running through some tests with it and wanted to share what I've found so far.

I ran this:

import pytabular
import logging
model = pytabular.Tabular(f"{pytabular.find_local_pbi_instances()[0][1]}")
pytabular.logger.setLevel(logging.DEBUG)
docs = pytabular.ModelDocumenter(model=model)
docs.generate_documentation_pages()
docs.save_documentation()

And got this:

Traceback (most recent call last):
  File "C:\Users\CStallings\Documents\daandocument\PyTabular\adhoc.py", line 6, in <module>
    docs = pytabular.ModelDocumenter(model=model)
  File "C:\Users\CStallings\Documents\daandocument\PyTabular\pytabular\document.py", line 66, in __init__
    self.friendly_name: str = self.set_model_friendly_name()
  File "C:\Users\CStallings\Documents\daandocument\PyTabular\pytabular\document.py", line 135, in set_model_friendly_name
    return (self.model.Catalog).replace(" ", "-").replace("_", "-").lower()
AttributeError: 'NoneType' object has no attribute 'replace'
           INFO     Disconnecting from - DVXTJW2\AnalysisServicesWorkspace_6656d45d-beaa-4e07-93be-1e7b1a84bf05 

pytabular.find_local_pbi_instances() will return connection strings of any open PBIX files, but those don't have a catalog with them. Could we have it first search for catalog, then try model.Database.Name as a backup? Or even improve the find_local_pbi_instances() if we need to. I wanted a python way to do what DAXStudio and TabularEditor were doing when they connected to local pbix files.

Example, a model I tested on is using mostly QueryPartitionSource. So, you would need to use Source.Query instead of Source.Expression. It might be best to have a method that can handle all the different PartitionSource types. It looks like you already have it written to handle M, Dax, etc. The one I was testing with was a SQL to an Azure SQL DB.

This is a real exciting feature, trying to think of any weird use cases someone could have that might break it. Some of the thoughts above, I don't think we need to wait to merge this in and could add in a later pull request, but do want to clean up some of the errors that could happen with unique use cases.

Daandamhuis commented 1 year ago

@Curts0:

I’ve added a Fallback scenario.

self.model_name = friendly_name or model.Catalog or model.Database.Name

It first checks if the a Friendly name is supplied, then the Catalog name and if all else fails the database name. The database name is the Power BI instance is a GUID like string, so best is if we can catch if it’s a local instance somewhere and then give a “hint” to the user, “<Please supply a friendly name, otherwise the docs folder will be xxxxxx-xxxxxx-xxxxx-xxxxx”.

import pytabular
import logging
model = pytabular.Tabular(f"{pytabular.find_local_pbi_instances()[0][1]}")
pytabular.logger.setLevel(logging.DEBUG)
docs = pytabular.ModelDocumenter(model=model, friendly_name=“Adventure Works”)
docs.generate_documentation_pages()
docs.save_documentation()

Also added a TRY-Catch to the get_msdrv() function, so it give a more clear error message. For some reason my Windows 11 installation gave an error on the powershell command.

Curts0 commented 1 year ago

Awesome thank you. Yeah, I like this. I'll go ahead and merge it so we can keep the pull requests relatively small and keep the momentum going. Excited to see where this goes. I'll work to get this into the next pypi release.