Merge branch 'main' into docs-description-lists

.github/workflows/ci-docs.yaml

@@ -21,6 +21,7 @@ jobs:
         run: |
           python -m pip install git+https://github.com/machow/quartodoc.git
           python -m pip install ".[all]"
+          pip install git+https://github.com/machow/quartodoc.git@5ed1430d4dc0e75414d0b11532ecd2393965b8d2
       - uses: quarto-dev/quarto-actions/setup@v2
       - name: Build docs
         run: |

docs/_quarto.yml

@@ -34,18 +34,24 @@ website:
             - get-started/basic-header.qmd
             - get-started/basic-stub.qmd
             - get-started/basic-column-labels.qmd
-        - section: Format and Style
+        - section: Format
           contents:
             - get-started/basic-formatting.qmd
+            - get-started/nanoplots.qmd
+        - section: Style
+          contents:
             - get-started/basic-styling.qmd
+            - get-started/targeted-styles.qmd
             - get-started/colorizing-with-data.qmd
+        - section: Theming
+          contents:
             - get-started/table-theme-options.qmd
             - get-started/table-theme-premade.qmd
-        - section: Extra Topics
+        - section: Selecting table parts
           contents:
             - get-started/column-selection.qmd
             - get-started/row-selection.qmd
-            - get-started/nanoplots.qmd
+            - get-started/loc-selection.qmd
 
 format:
   html:
@@ -87,7 +93,10 @@ quartodoc:
         class, we supply the input data table and some basic options for creating a stub and row
         groups (with the `rowname_col=` and `groupname_col=` arguments).
       contents:
-        - GT
+        - name: GT
+          children: linked
+
+
     - title: Creating or modifying parts of a table
       desc: >
         A table can contain a few useful components for conveying additional information. These
@@ -150,7 +159,18 @@ quartodoc:
         [`tab_style()`](`great_tables.GT.tab_style`) method). The styling classes allow for the
         specification of the styling properties to be applied to the targeted locations.
       contents:
+        - loc.header
+        - loc.title
+        - loc.subtitle
+        - loc.stubhead
+        - loc.column_header
+        - loc.spanner_labels
+        - loc.column_labels
+        - loc.stub
+        - loc.row_groups
         - loc.body
+        - loc.footer
+        - loc.source_notes
         - style.fill
         - style.text
         - style.borders
@@ -168,6 +188,7 @@ quartodoc:
         - md
         - html
         - from_column
+        - google_font
         - system_fonts
         - define_units
         - nanoplot_options
@@ -177,6 +198,7 @@ quartodoc:
         having to use `tab_options()` directly.
       contents:
         - GT.opt_align_table_header
+        - GT.opt_row_striping
         - GT.opt_all_caps
         - GT.opt_vertical_padding
         - GT.opt_horizontal_padding

docs/blog/introduction-0.12.0/index.qmd

@@ -0,0 +1,111 @@
+---
+title: "Great Tables `v0.12.0`: Google Fonts and zebra stripes"
+html-table-processing: none
+author: Rich Iannone
+date: 2024-09-30
+freeze: true
+jupyter: python3
+---
+
+In Great Tables `0.12.0` we focused on adding options for customizing the appearance of a table. In this post, we'll present two new features:
+
+- using typefaces from Google Fonts via `tab_style()` and `opt_table_font()`
+- adding table striping via `tab_options()` and `opt_row_striping()`
+
+Let's have a look at how these new features can be used!
+
+### Using fonts from Google Fonts
+
+Google Fonts is a free service that allows use of hosted typefaces in your own websites. In Great Tables, we added the `google_font()` helper function to easily incorporate such fonts in your tables. There are two ways to go about this:
+
+1. use `google_font()` with `opt_table_font()` to set a Google Font for the entire table
+2. invoke `google_font()` within `tab_style(styles=style.text(font=...))` to set the font within a location
+
+Let's start with this small table that uses the default set of fonts for the entire table.
+
+```{python}
+
+#| code-fold: true
+#| code-summary: "Show the code"
+
+from great_tables import GT, exibble, style, loc
+
+gt_tbl = (
+    GT(exibble.head(), rowname_col="row", groupname_col="group")
+    .cols_hide(columns=["char", "fctr", "date", "time"])
+    .tab_header(
+        title="A small piece of the exibble dataset",
+        subtitle="Displaying the first five rows (of eight)",
+    )
+    .tab_source_note(
+        source_note="This dataset is included in Great Tables."
+    )
+)
+
+gt_tbl
+```
+
+Now, with `opt_table_font()` + `google_font()`, we'll change the table's font to one from Google Fonts. I like [`Noto Serif`](https://fonts.google.com/noto/specimen/Noto+Serif) so let's use that here!
+
+```{python}
+from great_tables import GT, exibble, style, loc, google_font
+
+(
+    gt_tbl
+    .opt_table_font(font=google_font(name="Noto Serif"))
+)
+```
+
+Looking good! And we don't have to apply the font to the entire table. We might just wanted to use a Google Font in the table body. For that use case, `tab_style()` is the preferred method. Here's an example that uses the [`IBM Plex Mono`](https://fonts.google.com/specimen/IBM+Plex+Mono) typeface.
+
+```{python}
+(
+    gt_tbl
+    .tab_style(
+        style=style.text(font=google_font(name="IBM Plex Mono")),
+        locations=loc.body()
+    )
+)
+```
+
+Nice! And it's refreshing to see tables with fonts different from default set, as good as it might be. We kept the `google_font()` helper function as simple as possible, requiring only the font name in its `name=` argument. There are hundreds of fonts hosted on [Google Fonts](https://fonts.google.com) so look through the site, experiment, and find the fonts that you think look best in your tables!
+
+### Striping rows in your table
+
+Some people like having row striping (a.k.a. zebra stripes) in their display tables. We also know that some [advise against the practice](https://www.darkhorseanalytics.com/blog/clear-off-the-table/). We understand it's a controversial table issue, however, we also want to give you the creative freedom to just include the stripes. To that end, we now have that option in the package. There are two ways to enable this look:
+
+1. invoking `opt_row_striping()` to quickly set row stripes in the table body
+2. using some combination of three `row_striping_*` arguments in `tab_options()`
+
+Let's use that example table with `opt_row_striping()`.
+
+```{python}
+gt_tbl.opt_row_striping()
+```
+
+It's somewhat subtle but there is an alternating, slightly gray background (starting on the `"row_2"` row). The color is `#808080` but with an alpha (transparency) value of `0.05`.
+
+If this is not exactly what you want, there is an alternative to this. The `tab_options()` method has three new arguments:
+
+- `row_striping_background_color`: color to use for row striping
+- `row_striping_include_stub`: should striping include cells in the stub?
+- `row_striping_include_table_body`: should striping include cells in the body?
+
+With these new options, we can choose to stripe the *entire* row (stub cells + body cells) and use a darker color like `"lightblue"`.
+
+```{python}
+(
+    gt_tbl
+    .tab_options(
+        row_striping_background_color="lightblue",
+        row_striping_include_stub=True,
+        row_striping_include_table_body=True,
+    )
+)
+```
+
+These alternating fills can be a good idea in some table display circumstances. Now, you can make that call and the functionality is there to support your decision.
+
+### Wrapping up
+
+We are excited that this new functionality is now available in Great Tables. As ever, please let us know through [GitHub Issues](https://github.com/posit-dev/great-tables/issues) whether you ran into problems with any feature (new or old), or, if you have suggestions for further improvement!

docs/blog/introduction-0.2.0/index.qmd

@@ -59,7 +59,7 @@ wide_pops = (
         pl.col("country_code_2").is_in(["FM", "GU", "KI", "MH", "MP", "NR", "PW"])
         & pl.col("year").is_in([2000, 2010, 2020])
     )
-    .pivot(index="country_name", columns="year", values="population")
+    .pivot(index="country_name", on="year", values="population")
     .sort("2020", descending=True)
 )
 

docs/blog/pycon-2024-great-tables-are-possible/index.qmd

@@ -9,7 +9,7 @@ freeze: true
 The Great Tables crew is excited to share that we'll be presenting on tables at PyCon 2024!
 If you're around and want to meet, be sure to stop by the Posit Booth, or reach out on linkedin to [Rich](https://www.linkedin.com/in/richard-iannone-a5640017/) or [Michael](https://www.linkedin.com/in/michael-a-chow/)!
 
-The talk, Making Beautiful, Publication Quality Tables is Possible in 2024 is [10:45am Friday](https://us.pycon.org/2024/schedule/presentation/65/).
+The talk, Making Beautiful, Publication Quality Tables is Possible in 2024 happened on [May 17, 2024](https://us.pycon.org/2024/schedule/presentation/65/). You can watch the [recording on YouTube](https://youtu.be/08yLWPpFdo4?si=vBK9h-ObXNKp9tHH).
 
 In addition to the talk, there are two other events worth mentioning:
 
@@ -42,31 +42,25 @@ Note three important pieces:
 3. **The nanoplot** on the right shows a tiny bargraph for monthly sales over the past year.  This makes
    it easy to spot trends, and can be hovered over to get exact values.
 
-Critically, the code for this table used the DataFrame library [Polars](https://pola.rs/), which
-makes it really [easy to select rows and columns for styling](../polars-styling).
+Critically, the code for this table used the DataFrame library [Polars](https://pola.rs/), which makes it really [easy to select rows and columns for styling](../polars-styling/index.qmd).
 
 
 ## What's next?
 
 ### The 2024 Table Contest
 
-The world's premier display table contest---the [4th annual Table Contest](https://posit.co/blog/announcing-the-2024-table-contest/) draws competitors from near and far,
-to showcase the latest and greatest examples in table presentation.
-The contest is happening now, with **submissions due by May 31st, 2024**.
+The world's premier display table contest---the [4th annual Table Contest](https://posit.co/blog/announcing-the-2024-table-contest/) draws competitors from near and far, to showcase the latest and greatest examples in table presentation.
 
-For inspiration, see these resources:
-
-* [Contest announcement](https://posit.co/blog/announcing-the-2024-table-contest/)
-* [2022 winners and honorable mentions](https://posit.co/blog/winners-of-the-2022-table-contest/)
+The contest was a great success! On July 1, 2024 we announced the [2024 winners and honorable mentions](https://posit.co/blog/2024-table-contest-winners/). Check 'em out!
 
 
 ### posit::conf() workshop
 
-We're planning a posit::conf() 2024 workshop in August, called [Making Tables with gt and Great Tables](https://reg.conf.posit.co/flow/posit/positconf24/publiccatalog/page/publiccatalog/session/1707334049004001S0l2).
+We held a posit::conf() 2024 workshop, and you can find the materials at the [Making Tables with gt and Great Tables repo](https://github.com/posit-conf-2024/tables).
 
-If you're curious about making beautiful, publication quality tables in Python or R, we'd love to have you!
+If you're curious about making beautiful, publication quality tables in Python or R, do have a look at the resources at that GitHub repository.
 
-We’ll cover the following:
+We covered the following table topics:
 
 * Create table components and put them together (e.g., header, footer, stub, etc.)
 * Format cell values (numeric/scientific, date/datetime, etc.)
@@ -79,12 +73,11 @@ We’ll cover the following:
 
 Check out these resources to learn more about the wild and beautiful life of display tables:
 
-* [Great Tables example gallery](/docs/examples)
-* [The Design Philosophy of Great Tables (blog post)](http://localhost:6877/blog/design-philosophy/)
+* [Great Tables example gallery](../../examples/index.qmd)
+* [The Design Philosophy of Great Tables (blog post)](../design-philosophy/index.qmd)
 * [20 Minute Table Tutorial by Albert Rapp](https://youtu.be/ESyWcOFuMQc?si=1_bBRZEKENFKVNpB)
+* [PyCon talk: Making Beautiful, Publication Quality Tables is Possible in 2024](https://youtu.be/08yLWPpFdo4?si=vBK9h-ObXNKp9tHH)
 
 ## Hope all your tables are great!
 
-A huge thanks to all the people who have contributed to Great Tables over the past year.
-It's been a really incredible journey.
-Hope to see you at PyCon 2024!
+A huge thanks to all the people who have contributed to Great Tables over the past year. It's been a really incredible journey!

docs/blog/superbowl-squares/_code.py

@@ -41,10 +41,10 @@ def team_final_digits(game: pl.DataFrame, team_code: str) -> pl.DataFrame:
 # Cross and multiply p(digit | team=KC)p(digit | team=SF) to get
 # the joint probability p(digit_KC, digit_SF | KC, SF)
 joint = (
-    home.join(away, on="final_digit", how="cross")
+    home.join(away, how="cross")
     .with_columns(joint=pl.col("prop") * pl.col("prop_right"))
     .sort("final_digit", "final_digit_right")
-    .pivot(values="joint", columns="final_digit_right", index="final_digit")
+    .pivot(values="joint", on="final_digit_right", index="final_digit")
     .with_columns((cs.exclude("final_digit") * 100).round(1))
 )
 

docs/blog/superbowl-squares/index.qmd

@@ -47,7 +47,7 @@ df = (
     .with_columns(
         z=pl.when((pl.col("x") == 7) & (pl.col("y") == 4)).then(pl.lit("4/7")).otherwise("z")
     )
-    .pivot(index="x", values="z", columns="y")
+    .pivot(index="x", values="z", on="y")
     .with_row_index()
 )
 

docs/blog/tables-for-scientific-publishing/index.qmd

@@ -21,9 +21,9 @@ In this post, we'll review the big pieces that scientific tables need:
 We've added **six new datasets**, to help quickly show off scientific publishing! We'll use the new `reactions` and `gibraltar` datasets to create examples in the fields of Atmospheric Chemistry and Meteorology, respectively.
 
 :::{.callout-tip}
-Rich will be speaking on this at SciPy!
+Rich presented on this topic at SciPy 2024!
 
-If you're at SciPy 2024 in Tacoma, WA, Rich's talk is scheduled for July 11, 2024 (16:30–17:00 PT). The talk is called *Great Tables for Everyone* and it's sure to be both exciting and educational. If you're not attending that's okay, the talk is available [in GitHub](https://github.com/rich-iannone/presentations/tree/main/2024-07-11-SciPy-talk-GT).
+At SciPy 2024 (on July 11, 2024), Rich delivered a talk called *Great Tables for Everyone* and it presented some of the tables shown in this post. If you weren't in attendence that's okay, you can [watch the recorded talk](https://youtu.be/uvH-Z39ZUj0?si=3NVipMteXaeO3vb1) and the materials are available [in GitHub](https://github.com/rich-iannone/presentations/tree/main/2024-07-11-SciPy-talk-GT).
 :::
 
 ## Unit and scientific notation
@@ -160,5 +160,3 @@ Units notation is ever useful and it is applied in one of the column labels of t
 ## Hope all your (science-y) tables are great!
 
 We did scientific work pretty heavily in the past and so we understand that great tables in the realm of science publication is something that could and should be possible. We'll keep doing more to make this even better in upcoming releases.
-
-Hope to see you at SciPy 2024!

docs/get-started/basic-styling.qmd

@@ -1,5 +1,5 @@
 ---
-title: Stying the Table Body
+title: Styling the Table Body
 jupyter: python3
 html-table-processing: none
 ---

docs/get-started/colorizing-with-data.qmd

@@ -80,7 +80,7 @@ sza_pivot = (
     .filter((pl.col("latitude") == "20") & (pl.col("tst") <= "1200"))
     .select(pl.col("*").exclude("latitude"))
     .drop_nulls()
-    .pivot(values="sza", index="month", columns="tst", sort_columns=True)
+    .pivot(values="sza", index="month", on="tst", sort_columns=True)
 )
 
 (