Merge pull request #74 from posit-dev/feat-gt-add-divider

feat: `gt_add_divider()`

Author: juleswg23

docs/_quarto.yml

@@ -38,7 +38,9 @@ quartodoc:
 
   sections:
     - title: Plotting
-      desc: "" # TODO: add desc
+      desc: >
+        Functions to create various types of visualizations, such as bars, dots,
+        and win/loss charts, directly within columns of your existing `GT` objects.
       contents:
         - gt_plt_bar
         - gt_plt_bar_stack
@@ -48,14 +50,19 @@ quartodoc:
         - gt_plt_winloss
 
     - title: Colors
-      desc: "" # TODO: add desc
+      # TODO: revisit desc
+      desc: >
+        Functions to apply color-based formatting, highlight specific columns, or create colorful
+        styles with palettes that are easy on the eye.
       contents:
         - gt_color_box
         - gt_highlight_cols
         - gt_hulk_col_numeric
 
     - title: Themes
-      desc: Functions to generate themes.
+      desc: >
+        Predefined themes to style `GT` objects, inspired by popular design styles such as ESPN,
+        The Guardian, and Excel.
       contents:
         - gt_theme_538
         - gt_theme_dark
@@ -67,16 +74,23 @@ quartodoc:
         - gt_theme_pff
 
     - title: Icons and Images
-      desc: "" # TODO: add desc
+      # TODO: revisit desc
+      desc: >
+        Functions to enhance `GT` objects by adding icons, ratings, or images to cells
+        or headers alike.
       contents:
         - fa_icon_repeat
         - gt_fa_rating
         - img_header
 
-    - title: HTML and Formatting
-      desc: "" # TODO: add desc
+    - title: Utilities
+      # TODO: revisit desc
+      desc: >
+        Helper functions to extend `GT` functionality, including HTML features
+        and formatting tools.
       contents:
         - fmt_pct_extra
+        - gt_add_divider
         - gt_hyperlink
         - with_tooltip
 

docs/styles.css

@@ -2,7 +2,7 @@
     --bs-body-bg: white;
 }
 
-.sidebar {
+.sidebar-navigation {
     background-color: white !important;
 }
 

gt_extras/__init__.py

@@ -29,6 +29,8 @@
 
 from .images import img_header
 
+from .styling import gt_add_divider
+
 
 __all__ = [
     "gt_theme_538",
@@ -54,4 +56,5 @@
     "with_tooltip",
     "fmt_pct_extra",
     "img_header",
+    "gt_add_divider",
 ]

gt_extras/styling.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+from typing import Literal
+
+from great_tables import GT, style, loc
+from great_tables._tbl_data import SelectExpr
+
+
+__all__ = ["gt_add_divider"]
+
+
+def gt_add_divider(
+    gt: GT,
+    columns: SelectExpr,
+    sides: (
+        Literal["right", "left", "top", "bottom", "all"]
+        | list[Literal["right", "left", "top", "bottom", "all"]]
+    ) = "right",
+    color: str = "grey",
+    divider_style: Literal["solid", "dashed", "dotted", "hidden", "double"] = "solid",
+    weight: int = 2,
+    include_labels: bool = True,
+) -> GT:
+    """
+    Add dividers to specified columns in a GT table.
+
+    The `gt_add_divider()` function takes an existing `GT` object and adds dividers to the specified
+    columns. Dividers can be applied to one or more sides of the cells, with customizable color,
+    style, and weight. Optionally, dividers can also be applied to column labels.
+
+    Parameters
+    ----------
+    gt
+        A `GT` object to modify.
+
+    columns
+        The columns to which dividers should be applied.
+
+    sides
+        The sides of the cells where dividers should be added. Options include `"right"`, `"left"`,
+        `"top"`, `"bottom"`, or `"all"`. A list of sides can also be provided to apply dividers to
+        multiple sides.
+
+    color
+        The color of the dividers.
+
+    divider_style
+        The style of the dividers. Options include `"solid"`, `"dashed"`, `"dotted"`, `"hidden"`,
+        and `"double"`.
+
+    weight
+        The thickness of the dividers in pixels.
+
+    include_labels
+        Whether to include dividers in the column labels. If `True`, dividers will be applied to
+        both the body and the column labels. If `False`, dividers will only be applied to the body.
+
+    Returns
+    -------
+    GT
+        A `GT` object with dividers added to the specified columns.
+
+    Examples
+    --------
+    ```{python}
+    import pandas as pd
+    from great_tables import GT
+    from great_tables.data import peeps
+    import gt_extras as gte
+
+    peeps_mini = peeps.head(6)
+
+    gt = (
+        GT(peeps_mini)
+        .cols_hide([
+            "name_family", "postcode", "country", "country_code",
+            "dob", "gender", "state_prov", "email_addr",
+        ])
+        .tab_spanner("Location", ["address", "city"])
+        .tab_spanner("Body Measurements", ["height_cm", "weight_kg"])
+    )
+
+    gt.pipe(
+        gte.gt_add_divider,
+        columns="name_given",
+        color="#FFB90F",
+        divider_style="double",
+        weight=8,
+    ).pipe(
+        gte.gt_add_divider,
+        columns="phone_number",
+        color="purple",
+        sides=["right", "left"],
+        weight=5,
+    )
+    ```
+    """
+
+    locations = [loc.body(columns=columns)]
+
+    if include_labels:
+        locations.append(loc.column_labels(columns=columns))
+
+    res = gt.tab_style(
+        style=style.borders(
+            sides=sides,
+            color=color,
+            weight=weight,
+            style=divider_style,
+        ),
+        locations=locations,
+    )
+
+    return res

gt_extras/tests/test_styling.py

@@ -0,0 +1,61 @@
+import pytest
+import pandas as pd
+from great_tables import GT
+
+from gt_extras.styling import gt_add_divider
+
+
+@pytest.fixture
+def sample_gt():
+    sample_df = pd.DataFrame({"A": [1, 2], "B": [3, 4], "C": [5, 6]})
+    return GT(sample_df)
+
+
+def test_gt_add_divider_basic(sample_gt):
+    html = gt_add_divider(sample_gt, columns="A").as_raw_html()
+
+    assert html.count("border-right:") == 3
+    assert html.count("2px solid grey") == 3
+
+
+def test_gt_add_divider_multiple_columns(sample_gt):
+    html = gt_add_divider(sample_gt, columns=["A", "B"]).as_raw_html()
+
+    assert html.count("border-right: 2px solid grey") == 2 * 3
+
+
+def test_gt_add_divider_custom_sides(sample_gt):
+    html = gt_add_divider(sample_gt, columns="A", sides="left").as_raw_html()
+
+    assert html.count("border-left:") == 3
+    assert "border-right:" not in html
+
+
+def test_gt_add_divider_custom_color_and_style(sample_gt):
+    res = gt_add_divider(sample_gt, columns="A", color="blue", divider_style="dashed")
+    html = res.as_raw_html()
+
+    assert "border-right: 2px dashed blue;" in html
+    assert "grey" not in html
+
+
+def test_gt_add_divider_custom_weight(sample_gt):
+    html = gt_add_divider(sample_gt, columns="A", weight=5).as_raw_html()
+
+    assert "border-right: 5px solid grey;" in html
+    assert "2px solid grey" not in html
+
+
+def test_gt_add_divider_exclude_labels(sample_gt):
+    html = gt_add_divider(sample_gt, columns="A", include_labels=False).as_raw_html()
+
+    assert html.count("border-right:") == 2
+
+
+def test_gt_add_divider_multiple_sides(sample_gt):
+    html = gt_add_divider(sample_gt, columns="A", sides=["top", "bottom"]).as_raw_html()
+
+    assert "border-top:" in html
+    assert "border-bottom:" in html
+    assert "border-right:" not in html
+    assert "border-left:" not in html