Document `set_embed_options`

[joelostblom]

As per https://stackoverflow.com/questions/73476232/altair-disable-the-open-in-vega-editor-option-in-a-colab-jupyter-notebook I only see a mention in the changelog https://altair-viz.github.io/search.html?q=set_embed_options&check_keywords=yes&area=default

[dougthor42]

For the record, the function itself https://github.com/altair-viz/altair/blob/3e60c99f1ee2b80461a40412e1e0a9689da82f1a/altair/utils/display.py#L39 is documented, but it's just not part of the web docs, likely because the util package is not part of the sphinx docgen.

Though I will say that additional info could be useful. For example, it looks like setting set_embed_options has no effect on the result of the various Chart.to_X methods, which was surprising to me. Any additional documentation might want to include this fact.

>>> import altair as alt
>>> import pandas as pd
>>> df = pd.DataFrame({"x": [1, 2, 3, 4], "y": [1, 2, 3, 4], "name": ["A", "B", "C", "D"]})
>>> chart_wo_embed_opts = alt.Chart(df).mark_circle().encode(x="x:O", y="y:O")
>>> alt.renderers.set_embed_options(actions=False)
RendererRegistry.enable('default')
>>> chart_with_embed_opts = alt.Chart(df).mark_circle().encode(x="x:O", y="y:O")
>>> chart_wo_embed_opts.to_json() == chart_with_embed_opts.to_json()
True

Not sure if this is intended or not. If not, I'll open a separate Issue.

[jakevdp]

embed options do not affect the chart specification, they control the HTML and Javascript code used to display the chart specification in the frontend. That's why we need a weird global config rather than using a chart method that modifies the chart object.

[jakevdp]

You can check the effect like this, for example:

>>> import altair as alt
>>> import pandas as pd
>>> df = pd.DataFrame({"x": [1, 2, 3, 4], "y": [1, 2, 3, 4], "name": ["A", "B", "C", "D"]})
>>> chart = alt.Chart(df).mark_circle().encode(x="x:O", y="y:O")

>>> alt.renderers.set_embed_options(actions=False)
>>> html = chart._repr_mimebundle_()['text/html']  # _repr_mimebundle_ is what JupyterLab uses for rich display
>>> print('"actions": false' in html)
True
>>> print('"actions": true' in html)
False

>>> alt.renderers.set_embed_options(actions=True)
>>> html = chart._repr_mimebundle_()['text/html']
>>> print('"actions": false' in html)
False
>>> print('"actions": true' in html)
True

[dougthor42]

Thanks for the info - I figured it was intentional but I wanted to confirm.

Searching for set_embed_optoins came about because I'm trying to set some config that can be used for both colab/jupyter and flask+js. What I ended up doing on the flask+sj side was sending both the chart spec and the alt.renderers.options['embed_options'] to my HTML jinja2 template.