docs: add examples to the documentation

[jrycw]

Hello team,

This PR improves our documentation by adding missing examples, primarily for the vals module. The goal is to provide simple code snippets that users can easily copy and run.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.84%. Comparing base (2256e36) to head (bd3330e).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #618   +/-   ##
=======================================
  Coverage   90.84%   90.84%           
=======================================
  Files          46       46           
  Lines        5417     5417           
=======================================
  Hits         4921     4921           
  Misses        496      496           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[rich-iannone]

In this example, you could leave out all uses of the level= arg and still get the same result (because of the 'stacking' implementation). I say keep it, but remove the uses of level=.

Maybe a better example after that (after the 0-2 level one you added) is to use a level= when stacking works against you.

Perhaps some variation of this (could use a different dataset if preferred):

colnames = ["model", "hp", "hp_rpm", "trq", "trq_rpm"]

gtcars_mini = gtcars[colnames].head(10)

(
    GT(gtcars_mini)
    .tab_spanner(
        label="hp",
        columns=["hp", "hp_rpm"],
    )
    .tab_spanner(
        label="performance",
        columns=["hp", "hp_rpm", "trq", "trq_rpm", ],
    )
    .tab_spanner(
        label="trq",
        columns=["trq", "trq_rpm"],
        level=0
    )
)

In the above, if that last tab_spanner() didn't have level=0 it would be automatically in level 2. Instead, because there is space in level 0 above columns "trq" and "trq_rpm", it can be placed in level 0. I know you could modify the order of calls to avoid the level= use, but an example like this still seems useful for teaching how level= works.

[jrycw]

@rich-iannone , thanks for the great suggestion! It helps us introduce the stacked functionality and the level= parameter of tab_spanner() to users in a clearer way.

[rich-iannone]

Nice cross reference!

[rich-iannone]

These are welcome additions to our documentation! My only ask is to refine the extra examples for tab_spanner() (suggestions provided).

[rich-iannone]

LGTM!!