docs: Adds Vega-Altair Theme Test

[dangotbanned]

Related: #3519 (comment)

Description

This PR provides a recreation of Vega Theme Test using altair, accessible via the User Guide.

The primary benefit is to provide theme authors some sample code that they can use for testing the effects of their theme config.
I mentioned this in #3519 (comment), but I really think it is valuable to have a quick way to experiment across a wide range of chart/mark types.

Additionally, it serves as an example of composing a complex compound chart.
Compared to the existing compound_charts section - this features a range of data sources w/ a mix of shared/unique and local/url.

Video preview

2024-10-17.16-52-37.-.Embedded.redesign.mp4

See #3630 (comment) for initial version w/ pyscript

Screenshots

Code block

Collapsed

Expanded

The addition of this new directive allows directly referencing the contents of a function in the docs.

• feat: Adds .. altair-code-ref:: directive
• docs: Add folding code block for Vega-Altair Theme Test

There is also some interesting stuff in https://github.com/vega/altair/blob/3a5801edcbb0536b3031a32bc4984fdfe0d8fb8d/tools/codemod.py that can be adapted to support #3570 (comment).
The short explanation is this supports rewriting & reformatting code to be used elsewhere.
So this would have the benefit of writing in the same style as the rest of altair code, but support autoformatting for a possibly different style if agreed upon in #3519.

More generally though, a move towards writing code blocks in .py vs .rst has other benefits from a maintenance perspective:

• Code reusability
• Code blocks updating in response to IDE refactoring
• Clearer diffs during review
• Full access to tools like ruff, mypy to ensure code quality

Tasks

• Recreate charts used in demo
  • docs: Adds altair_theme_test.py provides a single chart adaptation of https://vega.github.io/vega-themes/
• Allow switching between themes
  • Working as of fix: Pass theme name to correct property
• Integrate into User Guide
  • docs: Link to vega-altair_theme_test.html in #chart-themes
  • Show (collapsible) code block used to create charts (thread)
• Reorganize and redocument ruff usage (0615228)
• Adapt alt_theme_test for User Guide template
  • comment 1
  • comment 2
  • Resolved:
    • docs: Redesign to fit User Guide template
    • docs: Adds Built-in Themes section

Deferred

• Refactor/move tests.altair_theme_test.py (thread)
  • I've made a start on this with (6e1ca94)
  • Could do with a second opinion on where these kinds of source snippets should sit
  • Uses mkdocs, but polars/docs/source/src

---

Outdated

An earlier version that did not use pyscript:

Separate html page

Screenshots

Ignore the slightly yellow hue. Seems to be an artifact of the screenshot itself

fivethirtyeight

latimes

vox

default

Current plan is for this link to replace the current link to Vega Theme Test

altair/doc/user_guide/customization.rst

Line 793 in 02ad17d

See `Vega Theme Test`_ for an interactive demo of themes inherited from `Vega Themes`_.

Notes

Theme Selection (Planning)

My understanding (not a web dev) of how switching between themes works in Vega Theme Test:

• Takes input from <select id="themes">
• Extracts value from selector #themes
• Storing config as theme
• Passing theme to https://github.com/vega/vega-embed

[dangotbanned]

@joelostblom do you have any ideas on how I'd go about integrating this into the User Guide?

I'm not sure if https://github.com/vega/sphinxext-altair would make sense here?

Edit

Just spotted these that could be relevant

• https://altair-viz.github.io/user_guide/saving_charts.html#html-format
• https://github.com/vega/altair/blob/main/doc/user_guide/saving_charts.rst#html-format
• https://github.com/vega/altair/blob/main/doc/_static/chart.html

[dangotbanned]

mypy issue in https://github.com/vega/altair/actions/runs/11194253679/job/31120512491?pr=3630 is unrelated to this PR

Fixed in #3632

[mattijn]

It would be helpful to highlight the edge cases of a theme. My main concern is indeed the overall width and height in combination with the number of data points. By setting each chart to 160x160 and reducing the data entries per chart to a minimum, we can fit 6 charts (in a 2x3 grid) within the user guide's template.

[dangotbanned]

It would be helpful to highlight the edge cases of a theme. My main concern is indeed the overall width and height in combination with the number of data points. By setting each chart to 160x160 and reducing the data entries per chart to a minimum, we can fit 6 charts (in a 2x3 grid) within the user guide's template.

@mattijn yeah that sounds like something we could try working towards.

I might need some help finding alternative examples that work better within these constraints.

Switching between these themes, you can see the varying height/width most clearly:

• quartz
• fivethirtyeight
• carbonwhite

Also we have the theme definitions in altair now, which is handy for this task

• https://github.com/vega/altair/blob/796649efd751a7b928ac4f81e192d0ae93f4a3d0/altair/vegalite/v5/schema/vega-themes.json

Notes

Using the variable names in alt_theme_test, these are my initial observations:

• geoshape, rect_heatmap
  • Probably the best candidates for limiting space
  • Both appear to cover roughly the same theme properties
  • Both are more niche mark types to use than the other examples
    • Maybe more so with geoshape, but for fields that need it I imagine it is vital
• bar_facet
  • None of the default themes have config specfic to facet

    • altair/altair/vegalite/v5/schema/_config.py

      Line 2169 in 796649e

      facet: CompositionConfigKwds

    • altair/altair/vegalite/v5/schema/_config.py

      Lines 2174 to 2176 in 796649e

      	headerColumn: HeaderConfigKwds
      	headerFacet: HeaderConfigKwds
      	headerRow: HeaderConfigKwds

  • Maybe replace that with a different example of a horizontal stacked bar?
    • Probably not using barley, as faceting on "year" is the point of that example
• bar
  • Absolutely need to keep a basic bar example, since it is so common
  • Since it is not using real data, we could use a smaller slice of "Index" to reduce width
• point, area
  • I've changed the dimensions of these quite a bit from the original
  • Currently, the axisX labels of urbaninstitute are already looking quite tight

---

@mattijn if you're available, any help towards this would be super appreciated.

Otherwise, I will loop back round to this part once I've finished off the work on the directive.
Got some quite funky results on a test I did yesterday, so I need to resolve a lot a of issues there

Bad generated html

Was attempting to create the dropdown using docutils.

Clearly misunderstood as these two look very different 😅

Fairly sure I can resolve this today though

[dangotbanned]

Otherwise, I will loop back round to this part once I've finished off the work on the directive. Got some quite funky results on a test I did yesterday, so I need to resolve a lot a of issues there

feat(DRAFT): Adds Functional altair-pyscript directive

As of the above commit, I've now got a working version in the docs

2024-10-14.15-08-04.WIP.Functional.PyScript.mp4

Still needs some cleaning up of the code and fitting the dimensions - but @mattijn your suggestion to use pyscript was the right call, thank you!

Edit

See updated version in description

[mattijn]

Awesome @dangotbanned! Really nice to see that this might be the first pyscript integration of an Altair chart within the documentation. And it actually works!

I can imagine we move elements of this into https://github.com/vega/sphinxext-altair.
Edit: in case you need it, I think you now have the rights to write to that repository too.

[joelostblom]

As of the above commit, I've now got a working version in the docs

Both beautiful and really useful! 🙌

[dangotbanned]

Awesome @dangotbanned! Really nice to see that this might be the first pyscript integration of an Altair chart within the documentation. And it actually works!

Edit: in case you need it, I think you now have the rights to write to that repository too.

Thanks x2 @mattijn

I can imagine we move elements of this into vega/sphinxext-altair.

Yeah I think some version of this would make sense there in the future.
I have left PyScriptDirective as a placeholder (at least) for now

altair/sphinxext/code_ref.py

Lines 244 to 245 in 99400d5

	class PyScriptDirective(SphinxDirective):
	"""Placeholder for non-theme related directive."""

I'd probably need to find out some more use cases for pyscript vs altair-plot- and pair that with the right options to expose in a directive.
It looks like there is quite a lot more you can do within the <script> tag.

---

In comparison, ThemeDirective (note to self, needs renaming) uses pyscript but also some other things that are less generally useful:

• Building up theme names from our annotations
• Populating a dropdown menu (select element)
• Referencing and rewriting code
  • python function -> embed within pyscript tag

These make a lot of sense here from a maintenance perspective (see Code Block in #3630 (comment)).
A more general case would probably want to support writing the code block inline (only or additionally), in a similar way to how vega/sphinxext-altair works via eval()

[dangotbanned]

One thing I think might come up is the choice of legend(orient="bottom")

I moved the legend for area, bar_stack since they took up a lot of horizontal space with orient="right".

Initially tried "top", but that didn't play nicely with every theme

Screenshot

Edit

Oh thanks for approving already @mattijn 😄

[mattijn]

Looks great 👍