Update html_formatter documentation

Author: kosiew

docs/source/user-guide/dataframe.rst

@@ -90,47 +90,128 @@ You can customize how DataFrames are rendered in HTML by configuring the formatt
 
 The formatter settings affect all DataFrames displayed after configuration.
 
-Performance Optimization with Shared Styles
-------------------------------------------
+Custom Style Providers
+----------------------
 
-The ``use_shared_styles`` parameter (enabled by default) optimizes performance when displaying 
-multiple DataFrames in notebook environments:
+For advanced styling needs, you can create a custom style provider:
 
 .. code-block:: python
 
+    from datafusion.html_formatter import StyleProvider, configure_formatter
+    
+    class MyStyleProvider(StyleProvider):
+        def get_table_styles(self):
+            return {
+                "table": "border-collapse: collapse; width: 100%;",
+                "th": "background-color: #007bff; color: white; padding: 8px; text-align: left;",
+                "td": "border: 1px solid #ddd; padding: 8px;",
+                "tr:nth-child(even)": "background-color: #f2f2f2;",
+            }
+            
+        def get_value_styles(self, dtype, value):
+            """Return custom styles for specific values"""
+            if dtype == "float" and value < 0:
+                return "color: red;"
+            return None
+    
+    # Apply the custom style provider
+    configure_formatter(style_provider=MyStyleProvider())
+
+Performance Optimization with Shared Styles
+-------------------------------------------
+The ``use_shared_styles`` parameter (enabled by default) optimizes performance when displaying 
+multiple DataFrames in notebook environments:
+
+ .. code-block:: python
+    from datafusion.html_formatter import StyleProvider, configure_formatter
     # Default: Use shared styles (recommended for notebooks)
     configure_formatter(use_shared_styles=True)
-    
+
     # Disable shared styles (each DataFrame includes its own styles)
     configure_formatter(use_shared_styles=False)
 
 When ``use_shared_styles=True``:
-
 - CSS styles and JavaScript are included only once per notebook session
 - This reduces HTML output size and prevents style duplication
 - Improves rendering performance with many DataFrames
 - Applies consistent styling across all DataFrames
 
-If you switch between notebooks or need to refresh styles:
+Creating a Custom Formatter
+---------------------------
+
+For complete control over rendering, you can implement a custom formatter:
 
 .. code-block:: python
 
-    from datafusion.html_formatter import reset_styles_loaded_state
+    from datafusion.html_formatter import Formatter, get_formatter
+    
+    class MyFormatter(Formatter):
+        def format_html(self, batches, schema, has_more=False, table_uuid=None):
+            # Create your custom HTML here
+            html = "<div class='my-custom-table'>"
+            # ... formatting logic ...
+            html += "</div>"
+            return html
     
-    # Force styles to be included in the next DataFrame display
-    reset_styles_loaded_state()
+    # Set as the global formatter
+    configure_formatter(formatter_class=MyFormatter)
+    
+    # Or use the formatter just for specific operations
+    formatter = get_formatter()
+    custom_html = formatter.format_html(batches, schema)
 
-Memory and Display Controls
---------------------------
+Managing Formatters
+-------------------
 
-You can control how much data is displayed and how much memory is used for rendering:
+Reset to default formatting:
+
+.. code-block:: python
+
+    from datafusion.html_formatter import reset_formatter
+    
+    # Reset to default settings
+    reset_formatter()
+
+Get the current formatter settings:
+
+.. code-block:: python
+
+    from datafusion.html_formatter import get_formatter
+    
+    formatter = get_formatter()
+    print(formatter.max_rows)
+    print(formatter.theme)
+
+Contextual Formatting
+---------------------
+
+You can also use a context manager to temporarily change formatting settings:
 
 .. code-block:: python
 
+    from datafusion.html_formatter import formatting_context
+    
+    # Default formatting
+    df.show()
+    
+    # Temporarily use different formatting
+    with formatting_context(max_rows=100, theme="dark"):
+        df.show()  # Will use the temporary settings
+    
+    # Back to default formatting
+    df.show()
+
+Memory and Display Controls
+---------------------------
+
+You can control how much data is displayed and how much memory is used for rendering:
+
+ .. code-block:: python
+ 
     configure_formatter(
         max_memory_bytes=4 * 1024 * 1024,  # 4MB maximum memory for display
         min_rows_display=50,               # Always show at least 50 rows
         repr_rows=20                       # Show 20 rows in __repr__ output
     )
 
-These parameters help balance comprehensive data display against performance considerations.
+These parameters help balance comprehensive data display against performance considerations.