putting some theme docs in

SuperCowPowers · Dec 5, 2024 · 63809ac · 63809ac
1 parent f500404
commit 63809ac
Show file tree

Hide file tree

Showing 4 changed files with 119 additions and 142 deletions.
diff --git a/docs/release_notes/0_8_78.md b/docs/release_notes/0_8_78.md
@@ -1,11 +1,11 @@
-# Release 0.8.74
+# Release 0.8.78
 
 !!!tip inline end "Need Help?"
     The SuperCowPowers team is happy to give any assistance needed when setting up AWS and SageWorks. So please contact us at [[email protected]](mailto:[email protected]) or on chat us up on [Discord](https://discord.gg/WHAJuz8sw8) 
 
 The SageWorks framework continues to flex to support different real world use cases when operating a set of production machine learning pipelines.
 
-**Note:** These release notes cover the changes from `0.8.71` to `0.8.74`
+**Note:** These release notes cover the changes from `0.8.74` to `0.8.78`
 
 
 ## General
@@ -14,38 +14,10 @@ This release is an incremental release as part of the road map for `v.0.9.0`. Pl
 ### S3 based Plugins
 We've added the ability to grab Dashboard plugins directly from an S3 bucket. Please see [Dashboard S3 Plugin](../admin/dashboard_s3_plugins.md)
 
-### Fixed Refresh Credentials 'Hang'
-The AWS credentials would get automatically refreshed each hour, but after 4 hours we were hitting an AWS 'refresh lock' that would lock up and never come back. That has been fixed, it will now properly give you a log message and throw an exception about needing to renew your `aws sso login` token/session.
+### TBD Stuff
 
 
 ## API Changes
-**Plugins**
-The directory that components were stored in was called 
-`web_components` that has now been changed to just `components`.
-
-**Web/View Import Changes**
-If you're using one of the existing web view those have been changed to `web_interface.page_views`.
-
-```
-from sageworks.web_views.data_source_web_view import DataSourceWebView
-from sageworks.web_interface.page_views.data_sources_page_view import DataSourcesPageView
-```
-
-More examples of how imports have changed
-
-```
-from sageworks.web_components import table
-<has been changed to>
-from sageworks.web_interface.components 
-```
-
-and
-
-```
-from sageworks.web_view.my_view
-<has been changed to>
-sageworks.web_interface.page_views.my_view
-```
 
 
 ## Specific Code Changes

diff --git a/docs/themes/details.md b/docs/themes/details.md
@@ -0,0 +1,94 @@
+# Theming Strategy for SageWorks Dashboard
+
+## **Phase 1: Application Start-Up Theming**
+This focuses on setting a polished, cohesive interface at startup. It ensures:
+
+1. **CSS and Plotly Templates at Start-Up**:
+   - The current system handles global styles via CSS (including Flask-served `custom.css`) and Plotly templates (via `pio.templates.default`) during app initialization.
+2. **Highly Customizable Interface**:
+   - By leveraging both custom CSS and Plotly templates, you can style everything to match branding and preferences.
+
+### **Why Phase 1 Works Well**
+- **Plotly Templates**: Figures are automatically styled if `pio.templates.default` is set before app initialization.
+- **CSS**: Dynamically affects the entire app without additional callbacks.
+- **Scalability**: Suitable for large apps since styles and templates are applied globally.
+
+<br><br>
+
+## **Phase 2: Dynamic Theme Switching**
+Dynamic theme switching allows users to toggle between themes (e.g., light and dark) at runtime. This is more complex, and splitting it into its own phase will reduce the complexity of each Phase.
+
+### **Challenges with Dynamic Switching**
+1. **Encapsulation Barriers**:
+   - A centralized callback for theme switching needs to know about every figure or component in the app, which is not scalable.
+2. **Dynamic Content/Plugins**:
+   - We have plugin pages, views, and components. A Typical app has 20 figures dynamically created, adding complexity to centralized callbacks.
+
+
+
+### **Proposed Solution: `set_theme()` Method**
+Introduce a `set_theme()` method in each component to manage its own updates:
+
+- **Figures**: Update their `layout.template` or regenerate themselves.
+- **HTML/CSS Components**: Dynamically update styles or toggle CSS classes.
+
+### **Advantages of `set_theme()`**
+1. **Encapsulation**:
+   - Each component knows how to update itself based on the theme.
+2. **Simple Callback**:
+   - The theme switch callback iterates through all registered components and calls their `set_theme()` method.
+3. **Scalable**:
+   - Suitable for multi-page apps with many dynamic components.
+
+
+
+## **How the Two Phases Work Together**
+### Phase 1:
+- **Focus**: Global theming at app start-up.
+- **What Works**:
+  - Plotly templates are applied to all figures by default.
+  - CSS styles are applied across the app.
+
+### Phase 2:
+- **Focus**: Extend components to dynamically update their theme.
+- **What to Add**:
+  - Extend components with a `set_theme(theme_name: str)` method.
+  - The callback triggers `set_theme()` for each registered component.
+
+
+
+## **Next Steps**
+- **Phase 1**: Finalize CSS and Plotly template integration for start-up theming.
+- **Phase 2**: Begin implementing a `set_theme()` system for individual components.
+
+<br><br><br>
+<br><br><br>
+
+
+## Storage
+### Theme Support in SageWorks
+For a Dash/Plotly web applications there are two main concepts that fall under the general umbrella of 'theme support'.
+
+### CSS for High-Level Theming
+- **Purpose**: Styles the overall **web interface** (e.g., layout, buttons, dropdowns, fonts, background colors).
+- **Scope**: Applies to **Dash components** (e.g., `dcc.Graph`, `dbc.Button`) and layout elements.
+- **Implementation**:
+  - Use a CSS file or a framework like Bootstrap.
+  - Dynamically switch themes (e.g., light/dark) using CSS class changes.
+
+### Templates for Plotly Figures
+- **Purpose**: Styles **Plotly figures** (e.g., background, gridlines, colorscales, font styles) to match the app's theme.
+- **Scope**: Only affects Plotly-generated visuals like charts, graphs, and heatmaps.
+- **Implementation**:
+  - Use predefined templates (e.g., `darkly`, `mintly`) or create custom JSON templates.
+  - Apply globally or on a per-figure basis.
+- **Great Resource**:
+    [dash-bootstrap-templates](https://github.com/AnnMarieW/dash-bootstrap-templates)
+### How They Complement Each Other
+1. **CSS handles the web app’s overall look**:
+
+    Example: A "dark mode" CSS class changes the app's background, text color, and component styles.
+
+2. **Templates handle Plotly-specific figure styling**:
+
+    Example: A "dark mode" Plotly template ensures charts have dark backgrounds, white gridlines, and matching font colors.
diff --git a/docs/themes/index.md b/docs/themes/index.md
@@ -1,3 +1,9 @@
+# Theme Support for SageWorks
+!!!tip inline end "Need Help?"
+    The SuperCowPowers team is happy to give any assistance needed when setting up AWS and SageWorks. So please contact us at [[email protected]](mailto:[email protected]) or on chat us up on [Discord](https://discord.gg/WHAJuz8sw8) 
+
+SageWorks interfaces are going to have full support for theming and branding to enable customizations of components, and pages. The theming support will include all of the default pages/components but will also support full theming for plugin components and pages [SageWorks Plugins](../plugins/index.md)
+
 # Summary of Theming Mechanisms
 
 ## 1. CSS Files
@@ -10,138 +16,42 @@ CSS affects **global styling** of the entire application, including:
 - Interactive element styling (e.g., hover effects, link colors).
 - Dash custom components.
 
----
 
-## 2. Plotly Templates
+## 2. Plotly Figure Templates
 Plotly templates control **figure-specific styling** for Plotly charts and graphs:
 
 - Axis styling (e.g., line colors, grid lines, and ticks).
-- Color scales for heatmaps, bar charts, and scatter plots.
+- Color scales for heatmaps, bar charts, and scatter plots.*
 - Marker and line styles.
 - Background colors for the figure and plot areas.
 - Font styles inside the figures.
 
----
 
-## 3. `data-bs-theme`
-The `data-bs-theme` attribute affects **Bootstrap-specific components**, primarily from **Dash Bootstrap Components (DBC)**:
+## 3. DBC Components Light/Dark
+The `data-bs-theme=light/dark` html attribute affects **Bootstrap-specific components**, primarily from **Dash Bootstrap Components (DBC)**:
 
 - Buttons.
 - Tables.
 - Forms (e.g., input boxes, checkboxes, radio buttons).
 - Cards, modals, and alerts.
 
----
-
-## Key Differences
-| **Aspect**            | **CSS Files**                | **Plotly Templates**       | **`data-bs-theme`**          |
-|------------------------|------------------------------|-----------------------------|------------------------------|
-| **Scope**             | Global app styling          | Plotly figures             | Bootstrap-specific elements |
-| **Dynamic Switching?** | Not easily (reloading needed)| Can update dynamically     | Supports dynamic switching  |
-
----
-
-## Conclusion
-For **Phase 1**:
-
-- **CSS Files**: Use for global look and feel.
-- **Plotly Templates**: Use for consistent chart/figure themes.
-- **`data-bs-theme`**: Use to control Bootstrap component styling.
-
-
-
-
-# Theming Strategy for SageWorks Dashboard
-
-## **Phase 1: Application Start-Up Theming**
-This focuses on setting a polished, cohesive interface at startup. It ensures:
-
-1. **CSS and Plotly Templates at Start-Up**:
-   - The current system handles global styles via CSS (including Flask-served `custom.css`) and Plotly templates (via `pio.templates.default`) during app initialization.
-2. **Highly Customizable Interface**:
-   - By leveraging both custom CSS and Plotly templates, you can style everything to match branding and preferences.
-
-### **Why Phase 1 Works Well**
-- **Plotly Templates**: Figures are automatically styled if `pio.templates.default` is set before app initialization.
-- **CSS**: Dynamically affects the entire app without additional callbacks.
-- **Scalability**: Suitable for large apps since styles and templates are applied globally.
 
-<br><br>
 
-## **Phase 2: Dynamic Theme Switching**
-Dynamic theme switching allows users to toggle between themes (e.g., light and dark) at runtime. This is more complex, and splitting it into its own phase will reduce the complexity of each Phase.
-
-### **Challenges with Dynamic Switching**
-1. **Encapsulation Barriers**:
-   - A centralized callback for theme switching needs to know about every figure or component in the app, which is not scalable.
-2. **Dynamic Content/Plugins**:
-   - We have plugin pages, views, and components. A Typical app has 20 figures dynamically created, adding complexity to centralized callbacks.
-
-
-
-### **Proposed Solution: `set_theme()` Method**
-Introduce a `set_theme()` method in each component to manage its own updates:
-
-- **Figures**: Update their `layout.template` or regenerate themselves.
-- **HTML/CSS Components**: Dynamically update styles or toggle CSS classes.
-
-### **Advantages of `set_theme()`**
-1. **Encapsulation**:
-   - Each component knows how to update itself based on the theme.
-2. **Simple Callback**:
-   - The theme switch callback iterates through all registered components and calls their `set_theme()` method.
-3. **Scalable**:
-   - Suitable for multi-page apps with many dynamic components.
-
-
-
-## **How the Two Phases Work Together**
-### Phase 1:
-- **Focus**: Global theming at app start-up.
-- **What Works**:
-  - Plotly templates are applied to all figures by default.
-  - CSS styles are applied across the app.
-
-### Phase 2:
-- **Focus**: Extend components to dynamically update their theme.
-- **What to Add**:
-  - Extend components with a `set_theme(theme_name: str)` method.
-  - The callback triggers `set_theme()` for each registered component.
-
-
-
-## **Next Steps**
-- **Phase 1**: Finalize CSS and Plotly template integration for start-up theming.
-- **Phase 2**: Begin implementing a `set_theme()` system for individual components.
+## Key Differences
 
-<br><br><br>
-<br><br><br>
+| <strong>Aspect</strong>            | <strong>CSS Files</strong>                | <strong>Plotly Templates</strong>       | <strong>DBC Dark/Light</strong>          |
+|------------------------------------|------------------------------------------|-----------------------------------------|------------------------------------------|
+| <strong>Scope</strong>             | Global app styling                      | Plotly figures                          | DBC Components                           |
+| <strong>Level of Control</strong>  | Full Range                              | Partial/Full*                           | Just Light and Dark                      |
+| <strong>Dynamic Switching?</strong>| Not easily (reloading needed)           | Can update dynamically                  | Supports dynamic switching               |
 
+* Some figure parameters will automatically work, but for stuff like colorscales the component code needs to 'pull' that from the template meta data when it updates it's figure.
 
-## Storage
-### Theme Support in SageWorks
-For a Dash/Plotly web applications there are two main concepts that fall under the general umbrella of 'theme support'.
+## Additional Resources
 
-### CSS for High-Level Theming
-- **Purpose**: Styles the overall **web interface** (e.g., layout, buttons, dropdowns, fonts, background colors).
-- **Scope**: Applies to **Dash components** (e.g., `dcc.Graph`, `dbc.Button`) and layout elements.
-- **Implementation**:
-  - Use a CSS file or a framework like Bootstrap.
-  - Dynamically switch themes (e.g., light/dark) using CSS class changes.
+<img align="right" src="../images/scp.png" width="180">
 
-### Templates for Plotly Figures
-- **Purpose**: Styles **Plotly figures** (e.g., background, gridlines, colorscales, font styles) to match the app's theme.
-- **Scope**: Only affects Plotly-generated visuals like charts, graphs, and heatmaps.
-- **Implementation**:
-  - Use predefined templates (e.g., `darkly`, `mintly`) or create custom JSON templates.
-  - Apply globally or on a per-figure basis.
-- **Great Resource**:
-    [dash-bootstrap-templates](https://github.com/AnnMarieW/dash-bootstrap-templates)
-### How They Complement Each Other
-1. **CSS handles the web app’s overall look**:
+Need help with plugins? Want to develop a customized application tailored to your business needs?
 
-    Example: A "dark mode" CSS class changes the app's background, text color, and component styles.
+- Consulting Available: [SuperCowPowers LLC](https://www.supercowpowers.com)
 
-2. **Templates handle Plotly-specific figure styling**:
-
-    Example: A "dark mode" Plotly template ensures charts have dark backgrounds, white gridlines, and matching font colors.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -25,6 +25,7 @@ nav:
     - Cached Endpoint: cached/cached_endpoint.md
   - Theme Support:
     - Overview: themes/index.md
+    - Support Phases (WIP): themes/details.md
   - Blogs: 
     - OverView: blogs/index.md
     - Residual Analysis: blogs/residual_analysis.md