more doccumentation changes

Author: Russell-Shean

docs/_quarto.yml

@@ -37,7 +37,7 @@ quartodoc:
 
   sections:
     - title: Power Bpy
-      desc: The first thing you should create is an instance of the Dashboard class. Then use the `add_page()` or `load_page()` functions to attach instances of the internal `_Page` class. All methods are attached to either dashboards or pages. Click below to see which methods are attached to which. For more details about how to build dashboards, see the test dashboard [tutorial](https://www.russellshean.com/powerbpy/example_dashboards/Test%20Dashboard/Testing%20Dashboard.html) section of this website.
+      desc: The first thing you should create is an instance of the Dashboard class. Then use the `add_page()` or `load_page()` functions to attach instances of the internal `_Page` class to the Dashboard. All methods are attached to either dashboards or pages. Click below to see which methods are attached to which. For more details about how to build dashboards, see the test dashboard [tutorial](https://www.russellshean.com/powerbpy/example_dashboards/Test%20Dashboard/Testing%20Dashboard.html) section of this website.
       contents:
         # the functions being documented in the package.
         # you can refer to anything: class methods, modules, etc..

docs/basic_setup.qmd

@@ -1,19 +1,24 @@
 ---
-title: "basic_setup"
+title: "Setup Python Environment"
 format: html
 ---
 
-# Setup
-## Python
-1. Make sure [python](https://www.python.org/downloads/) is installed on your computer.
+# Setup  
+This document briefly covers how to setup your python environment so you can start using the package to build dashboard. If anything doesn't make sense, please open a pull request or issue so I can improve this documentation. While you're waiting for me to fix the doccumentation, there are numerous other tutorials online that explain how to install python, create virtual environments and run python scripts.         
+   
+## Python      
+     
+   1. Make sure [python](https://www.python.org/downloads/) is installed on your computer.       
+        
+## Create virtual environment       
+For this example, we're going to use a virtual environment to keep the package versions separate from what you have installed on your system     
 
-## Create virtual environment
-For this example, we're going to use a virtual environment to keep the package versions separate from what you have installed on your system
-1. Open a command prompt and navigate to the folder you want to create dashboards in by running the following:
+   1. Open a command prompt and navigate to the folder you want to create dashboards in by running the following:
    ```shell
    cd path/to/your/folder
    ```
-2. Create and activate a virtual environment by running the same:
+   
+   2. Create and activate a virtual environment by running the same:
    ```shell
    # create a virtual environment
    python -m venv venv
@@ -25,46 +30,21 @@ For this example, we're going to use a virtual environment to keep the package v
    # source venv/bin/activate
    ```
 
-2. Install the Power Bpy module:
+   2. Install the Power Bpy module:
    ```shell
    # install the Power Bpy module
    pip install powerbpy
-   ```
+   ```     
+   3. Write a script to create a dashboard. (This one's up to you!)
 
-3. Write a script to create a dashboard. (This one's up to you!)
-
-4. When you're ready to create the dashboard, run the script by running the following in the command prompt window.
-
-  ```shell
-  python name_of_your_script.py
-  ```     
+   4. When you're ready to create the dashboard, run the script by running the following in the command prompt window.     ```shell
+   python name_of_your_script.py
+   ```     
   
   
-## Install dependencies
-1. Install python        
-You'll need to install python. Here are some <a href="https://www.geeksforgeeks.org/download-and-install-python-3-latest-version/">instructions</a>    
-2. Install Power Bpy    
-The `{powerbpy}` package isn't on pypi yet, so you'll need to install it from github. <a href="https://www.lifewire.com/how-to-open-command-prompt-2618089">Open a terminal</a> and enter the following:     
-    
+## Development version
+To install the latest version of Power Bpy from Github instead of Pypi you can run the following
 ```dosbat     
-py -m pip install git+https://github.com/Russell-Shean/powerbpy.git#egg=powerbpy     
+python -m pip install git+https://github.com/Russell-Shean/powerbpy.git#egg=powerbpy     
 ```     
 
-After the package is on pypi, you'll be able to install it using this: 
-```batchfile
-py -m pip install powerbpy
-```
-   
-## Executing python scripts   
-That's all you need to install! To create the dashboards, you'll need to either run the commands in a terminal, or use a text editor to save the commands in a a script. I recomend starting with a text editor, because as your dashboard grows more complex, it'll be helpful to have everything saved in a script. Many text editors have an option to execute a script directly from the editor. You can also execute the scripts from the terminal using the following command:     
-```dosbat
-py build_dashboard.py
-```  
-This assumes that you named your script `build_dashboard.py` and the command prompt's current directory is the folder storing `build_dashboard.py`. You can change the current directory of the terminal using the `cd` command. For example you can use the following to move into `C:/Users/`:     
-```dosbat
-cd C:/Users/
-```
-You can also use full or relative paths from the current directory to the python script without changing the current working directory. For example if you start in your `%userprofile%` (`C:/Users/[your username]`) and the python script is stored at `C:/Users/[your username]/python_projects/build_dashboard.py`, you can execute the script with the following:     
-```dosbat      
-py python_projects/build_dashboard.py    
-```    

docs/example_dashboards/Sanky Chart and Table/chart_and_table.qmd

@@ -7,7 +7,7 @@ image: "https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sa
 
 # Sanky Chart and Table      
 I used the PowerBpy python module to recreate an <a href="https://workout-wednesday.com/pbi-2025-w13/">sanky chart and table</a> dashboard from the <a href="https://workout-wednesday.com/">Workout Wednesday Group</a> challenge. Here's a screenshot of the original dashboard (top) and the dashboard I recreated using Power Bpy (bottom). (It appears that the data has changed since the original author created his dashboard, so my version and his look a bit different because the data is a bit different, but the overall format is pretty similiar). The rest of the blog will describe key parts of the code I used to make the dashboard. The full code is available [here](https://github.com/Russell-Shean/powerbpy-demos/tree/main/WOW/2025/13).      
-<img id="my-sanky-img" src="https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sanky_screenshot.png" style="margin-bottom:10px">      
+<img id="my-sanky-img" class="img-fluid" src="https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sanky_screenshot.png" style="margin-bottom:10px">      
 ![wow sanky](https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/WOW_sanky.png)
 
 ## Assumptions
@@ -165,7 +165,8 @@ sales_by_store_and_date = (
 
 
 # undo the multi indexing of column names
-# (I don't even want to try to imagine how Power BI would try to handle multi-indexed columns lol)
+# (I don't even want to try to imagine how Power BI 
+#   would try to handle multi-indexed columns lol)
 sales_by_store_and_date.columns = [
     f"{val}_{col}" for val, col in sales_by_store_and_date.columns
 ]

docs/example_dashboards/Test Dashboard/Testing Dashboard.qmd

@@ -18,7 +18,7 @@ This example shows how I create the dashboard I use for testing the module. It i
 
 
 # Setup    
-If you don't already have python and the `{powerbpy}` module installed, please refer to the setup instructions first. 
+If you don't already have python and the `{powerbpy}` module installed, please refer to the setup [instructions](https://www.russellshean.com/powerbpy/basic_setup.html) first. 
 
 # Build dashboards   
 ## Create a new dashboard
@@ -134,7 +134,7 @@ page1.add_chart(visual_id = "colonies_lost_by_year",
 Here's what the chart that we added looks like:      
 ![image](https://github.com/Russell-Shean/powerbpy/blob/main/docs/assets/images/add_chart_example.png?raw=true)     
 
-# Add a text box    
+## Add a text box    
 In addition to visuals, many dashboards use explanatory text. Here's an example of adding a text box to a page. The following arguments are required:      
 
   1. `text` - The text you want to display in the box         
@@ -214,7 +214,11 @@ Often we have data that is tied to geographic regions that can be respresented b
 
 This function does a lot under the hood so you don't have to. It creates measures in the dataset so that bins will automatically adjust when filtering conditions change, it creates the map and adds text boxes for a legend and and a slicer to allow the user to filter the data. The method requires you to provide a shape file that corresponds to a variable in your dataset. For example, the dataset could have two columns: US states and average income. In this case you should provide a shapefile of US states.     
 
-The method also give two different options for binning the data and assigning ranges of values to different colors on the map. You can only specify one of the two options at a time. The first option is to provide a static set of breaks that you define yourself. This is ideal if you already know the structure of your data and how you want to assign ranges of values  to different colors. Use the `static_bin_breaks` argument to pass an integer list of break values. The second option is to provide a list of percentiles that you want to use to bin the data into ranges. This option is intended to be used in conjunction with a third variable that you use to filter the data. For example, assume you have a third variable in your dataset of average income by state dataset, maybe age. You could pass age to the `filtering_var` argument to create a slicer attached to the map that filters the dataset by age before rerendering the map. You could then pass the list of percentiles to `percentile_bin_breaks` such as 0, 0.2, 0.4, 0.6, 0.8, 1. This will create breaks between 0% and 20%, 20% and 40%, etc and the bins will be recalculated each time the slicer filters are adjusted. So, for this example, if you selected "young people" in the slicer, the bins will be re-calculated and the map will re-render to show 20, 40, 60 etc, percentiles for just young people. If you provide `percentile_bin_breaks` you must also provide a `filtering_var`; the assumption being that if you don't need dynamic recalculation of bins based on the filtering variable, you'd be better off calculating a static set of breaks for yourself and passing them as a list to `static_bin_breaks`. 
+The method also give two different options for binning the data and assigning ranges of values to different colors on the map. You can only specify one of the two options at a time.       
+    
+The first option is to provide a static set of breaks that you define yourself. This is ideal if you already know the structure of your data and how you want to assign ranges of values  to different colors. Use the `static_bin_breaks` argument to pass an integer list of break values.        
+      
+The second option is to provide a list of percentiles that you want to use to bin the data into ranges. This option is intended to be used in conjunction with a third variable that you use to filter the data. For example, assume you have a third variable in your dataset of average income by state dataset, maybe age. You could pass age to the `filtering_var` argument to create a slicer attached to the map that filters the dataset by age before rerendering the map. You could then pass the list of percentiles to `percentile_bin_breaks` such as 0, 0.2, 0.4, 0.6, 0.8, 1. This will create breaks between 0% and 20%, 20% and 40%, etc and the bins will be recalculated each time the slicer filters are adjusted. So, for this example, if you selected "young people" in the slicer, the bins will be re-calculated and the map will re-render to show 20, 40, 60 etc, percentiles for just young people. If you provide `percentile_bin_breaks` you must also provide a `filtering_var`; the assumption being that if you don't need dynamic recalculation of bins based on the filtering variable, you'd be better off calculating a static set of breaks for yourself and passing them as a list to `static_bin_breaks`. 
 
 I'll describe in more detail below some of the optional method arguments and how they can be used to customize your map. But first, here are the required arguments: 
 
@@ -224,10 +228,7 @@ I'll describe in more detail below some of the optional method arguments and how
   4. `map_title` - The title you want to put above the map.
   5. `location_var` - The name of the column in data_source that you want to use for the location variable on the map. This should also correspond to the geography of your shape file.
   6. color_var: The name of the column in data_source that you want to use for the color variable on the map. This variable should be numeric.
-        filtering_var: str
-            Optional. The name of a column in data source that you want to use to filter the color variable on the map. This must be supplied if providing percentile_bin_breaks. If you want to use percentiles without filtering (ie on static data), you should calculate the percentiles yourself and pass them to static_bin_breaks. Do not provide both static_bin_breaks and a filtering_var.
-        static_bin_breaks: list
-            This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc. A filtering_var cannot be provided if static_bin_breaks is provided. Use percentile bin breaks instead.
+        
         color_palatte: list
             A list of hex codes to use to color your data. There should be one fewer than the number of entries in static_bin_breaks
         add_legend: bool

src/powerbpy/page.py

@@ -9,7 +9,7 @@
 class _Page:
     '''A python class used to model a power BI dashboard page.
 
-    You should never initate a page class directly, instead use Dashboard.new_page() to create a new page, or Dashboard.load_page() to load an existing page. This class is important however because its methods are public. The reason you should never create an instance of the _Page class directly is simple -- it doesn't make sense to have a page not attached to a dashboard.
+    You should never initate a page class directly, instead use `Dashboard.new_page()` to create a new page, or `Dashboard.load_page()` to load an existing page. This class is important however because its methods are public. The reason you should never create an instance of the _Page class directly is simple -- it doesn't make sense to have a page not attached to a dashboard.
 
     Here's an example workflow:
     ```python
@@ -566,7 +566,7 @@ def add_shape_map(self,
         static_bin_breaks: list
             This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc. A filtering_var cannot be provided if static_bin_breaks is provided. Use percentile bin breaks instead.
         color_palette: list
-            A list of hex codes to use to color your data. There should be one fewer than the number of entries in static_bin_breaks
+            A list of hex codes to use to color your data. There should be one fewer than the number of bins.
         add_legend: bool
             True or False, would you like to add the default legend? (By default legend, I mean this function's default, not the Power BI default)
         static_bin_breaks: list

src/powerbpy/shape_map.py

@@ -65,7 +65,7 @@ def __init__(self,
         static_bin_breaks: list
             This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc. A filtering_var cannot be provided if static_bin_breaks is provided. Use percentile bin breaks instead.
         color_palatte: list
-            A list of hex codes to use to color your data. There should be one fewer than the number of entries in static_bin_breaks
+            A list of hex codes to use to color your data. There should be one fewer than the number of bins.
         add_legend: bool
             True or False, would you like to add the default legend? (By default legend, I mean this function's default, not the Power BI default)
         static_bin_breaks: list