Update html_formatter documentation

Author: kosiew

docs/source/user-guide/dataframe.rst

@@ -75,62 +75,105 @@ You can customize how DataFrames are rendered in HTML by configuring the formatt
     
     # Change the default styling
     configure_formatter(
-        max_cell_length=25,        # Maximum characters in a cell before truncation
-        max_width=1000,            # Maximum width in pixels
-        max_height=300,            # Maximum height in pixels
-        max_memory_bytes=2097152,  # Maximum memory for rendering (2MB)
-        min_rows_display=20,       # Minimum number of rows to display
-        repr_rows=10,              # Number of rows to display in __repr__
-        enable_cell_expansion=True,# Allow expanding truncated cells
-        custom_css=None,           # Additional custom CSS
-        show_truncation_message=True, # Show message when data is truncated
-        style_provider=None,       # Custom styling provider
-        use_shared_styles=True     # Share styles across tables
+        max_rows=50,           # Maximum number of rows to display
+        max_width=None,        # Maximum width in pixels (None for auto)
+        theme="light",         # Theme: "light" or "dark" 
+        precision=2,           # Floating point precision
+        thousands_separator=",", # Separator for thousands
+        date_format="%Y-%m-%d", # Date format
+        truncate_width=20      # Max width for string columns before truncating
     )
 
 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
 
-    # Default: Use shared styles (recommended for notebooks)
-    configure_formatter(use_shared_styles=True)
+    from datafusion.html_formatter import StyleProvider, configure_formatter
     
-    # Disable shared styles (each DataFrame includes its own styles)
-    configure_formatter(use_shared_styles=False)
-
-When ``use_shared_styles=True``:
+    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())
 
-- 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
+Creating a Custom Formatter
+---------------------------
 
-If you switch between notebooks or need to refresh styles:
+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
 
-    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
-    )
+    from datafusion.html_formatter import reset_formatter
+    
+    # Reset to default settings
+    reset_formatter()
+
+Get the current formatter settings:
+
+.. code-block:: python
 
-These parameters help balance comprehensive data display against performance considerations.
+    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()