Prefer method-based syntax in docs and add tabbed interface for metho…

…d and attribute syntax in gallery (#2983)

* Add tabbed syntax for gallery examples

* Add option to remove altair plot code to avoid duplication

* Include methods syntax code for example that do not exist in the directoy and note when the code is the same

* Blacken

* Switch to method-based syntax for getting started section

* Clarify explanation of different encoding channel option syntaxes

* Switch to method-based syntax for encoding section

* Switch to method-based syntax for arc and area marks

* Add missing example to methods gallery

* Switch to method-based syntax for bar, box, errbar, errorband marks

* Switch to method-based syntax for geoshape, line, point, rect, rule, and text marks

* Clarify syntax of trail mark example

* Switch to method-based syntax for transforms

* Switch to method-based syntax for compound charts

* Switch to method-based syntax for customization section

* Switch to method-based syntax for time and dates section

* Switch to method-based syntax for the guides section

* Switch to method-based syntax for the large datasets section

* Switch to method-based syntax for the tutorial section

* Clarify that docs now use method-based syntax

* Apply suggestions from code review

Co-authored-by: Stefan Binder <binder_stefan@outlook.com>

* Fix duplication in requirements

* Change to method based syntax

* Fix formatting

---------

Co-authored-by: Stefan Binder <binder_stefan@outlook.com>

doc/case_studies/exploring-weather.rst

@@ -54,7 +54,7 @@ The result is a histogram of precipitation values:
 .. altair-plot::
 
     alt.Chart(df).mark_bar().encode(
-        alt.X('precipitation', bin=True),
+        alt.X('precipitation').bin(),
         y='count()'
     )
 
@@ -177,7 +177,7 @@ meaning of the plot more clear:
 .. altair-plot::
 
     alt.Chart(df).mark_bar().encode(
-        x=alt.X('month(date):N', title='Month of the year'),
+        x=alt.X('month(date):N').title('Month of the year'),
         y='count()',
         color=alt.Color('weather', legend=alt.Legend(title='Weather type'), scale=scale),
     )
@@ -191,10 +191,10 @@ and to allow interactive panning and zooming with the mouse:
 .. altair-plot::
 
     alt.Chart(df).mark_point().encode(
-        alt.X('temp_max', title='Maximum Daily Temperature (C)'),
-        alt.Y('temp_range:Q', title='Daily Temperature Range (C)'),
-        alt.Color('weather', scale=scale),
-        alt.Size('precipitation', scale=alt.Scale(range=[1, 200]))
+        alt.X('temp_max').title('Maximum Daily Temperature (C)'),
+        alt.Y('temp_range:Q').title('Daily Temperature Range (C)'),
+        alt.Color('weather').scale(scale),
+        alt.Size('precipitation').scale(range=[1, 200])
     ).transform_calculate(
         "temp_range", "datum.temp_max - datum.temp_min"
     ).properties(
@@ -215,7 +215,7 @@ by weather type:
     alt.Chart(df).mark_bar().encode(
         x='count()',
         y='weather:N',
-        color=alt.Color('weather:N', scale=scale),
+        color=alt.Color('weather:N').scale(scale),
     )
 
 And now we can vertically concatenate this histogram to the points plot above,
@@ -228,10 +228,10 @@ of the selection (for more information on selections, see
     brush = alt.selection_interval()
 
     points = alt.Chart().mark_point().encode(
-        alt.X('temp_max:Q', title='Maximum Daily Temperature (C)'),
-        alt.Y('temp_range:Q', title='Daily Temperature Range (C)'),
+        alt.X('temp_max:Q').title('Maximum Daily Temperature (C)'),
+        alt.Y('temp_range:Q').title('Daily Temperature Range (C)'),
         color=alt.condition(brush, 'weather:N', alt.value('lightgray'), scale=scale),
-        size=alt.Size('precipitation:Q', scale=alt.Scale(range=[1, 200]))
+        size=alt.Size('precipitation:Q').scale(range=[1, 200])
     ).transform_calculate(
         "temp_range", "datum.temp_max - datum.temp_min"
     ).properties(
@@ -244,7 +244,7 @@ of the selection (for more information on selections, see
     bars = alt.Chart().mark_bar().encode(
         x='count()',
         y='weather:N',
-        color=alt.Color('weather:N', scale=scale),
+        color=alt.Color('weather:N').scale(scale),
     ).transform_calculate(
         "temp_range", "datum.temp_max - datum.temp_min"
     ).transform_filter(

doc/conf.py

@@ -40,7 +40,7 @@
     "sphinxext.altairgallery",
     "sphinxext.schematable",
     "sphinx_copybutton",
-    # "sphinxext.rediraffe",
+    "sphinx_design",
 ]
 
 altair_plot_links = {"editor": True, "source": False, "export": False}

doc/getting_started/starting.rst

@@ -221,16 +221,16 @@ Customizing your Visualization
 By default, Altair via Vega-Lite makes some choices about default properties
 of the visualization.
 Altair also provides an API to customize the look of the visualization.
-For example, we can specify the axis titles using the ``axis`` attribute
-of channel classes, and we can specify the color of the marking by setting
-the ``color`` keyword of the ``Chart.mark_*`` methods to any valid HTML
+For example, we can specify the axis titles using the :meth:`title` method
+of channel classes, and we can specify the color of the mark by setting
+the ``color`` keyword of the ``Chart.mark_*`` method to any valid HTML
 color string:
 
 .. altair-plot::
 
     alt.Chart(data).mark_bar(color='firebrick').encode(
-        alt.Y('a', title='category'),
-        alt.X('average(b)', title='avg(b) by category')
+        alt.Y('a').title('category'),
+        alt.X('average(b)').title('avg(b) by category')
     )
 
 

doc/releases/changes.rst

@@ -29,7 +29,7 @@ Enhancements
 Grammar Changes
 ~~~~~~~~~~~~~~~
 
-- Channel options can now be set via a method based syntax in addition to the previous helper class syntax. For example, in addition to ``alt.X(..., bin=alt.Bin(...))`` it is now possible to do ``alt.X(...).bin(...)```) (#2795). See :ref:`method-based-attribute-setting` for details.
+- Channel options can now be set via a more convenient method-based syntax in addition to the previous attribute-based syntax. For example, instead of ``alt.X(..., bin=alt.Bin(...))`` it is now recommend to use ``alt.X(...).bin(...)```) (#2795). See :ref:`method-based-attribute-setting` for details.
 - ``selection_single`` and ``selection_multi`` are now deprecated; use ``selection_point`` instead.  Similarly, ``type=point`` should be used instead of ``type=single`` and ``type=multi``.
 - ``add_selection`` is deprecated; use ``add_params`` instead.
 - The ``selection`` keyword argument must in many cases be replaced by ``param`` (e.g., when specifying a filter transform).

doc/requirements.txt

@@ -7,3 +7,4 @@ pydata-sphinx-theme
 geopandas
 myst-parser
 sphinx_copybutton
+sphinx-design

doc/user_guide/compound_charts.rst

@@ -34,17 +34,16 @@ same data; for example:
 .. altair-plot::
 
     import altair as alt
-    from altair.expr import datum
-
     from vega_datasets import data
+
     stocks = data.stocks.url
 
     base = alt.Chart(stocks).encode(
         x='date:T',
         y='price:Q',
         color='symbol:N'
     ).transform_filter(
-        datum.symbol == 'GOOG'
+        alt.datum.symbol == 'GOOG'
     )
 
     base.mark_line() + base.mark_point()
@@ -82,9 +81,9 @@ heat-map:
     source = data.movies.url
 
     heatmap = alt.Chart(source).mark_rect().encode(
-        alt.X('IMDB_Rating:Q', bin=True),
-        alt.Y('Rotten_Tomatoes_Rating:Q', bin=True),
-        alt.Color('count()', scale=alt.Scale(scheme='greenblue'))
+        alt.X('IMDB_Rating:Q').bin(),
+        alt.Y('Rotten_Tomatoes_Rating:Q').bin(),
+        alt.Color('count()').scale(scheme='greenblue')
     )
 
     points = alt.Chart(source).mark_circle(
@@ -137,7 +136,7 @@ distribution of its points:
 
     chart2 = alt.Chart(iris).mark_bar().encode(
         x='count()',
-        y=alt.Y('petalWidth:Q', bin=alt.Bin(maxbins=30)),
+        y=alt.Y('petalWidth:Q').bin(maxbins=30),
         color='species:N'
     ).properties(
         height=300,
@@ -189,9 +188,7 @@ with a ``brush`` selection to add interaction:
         height=200
     )
 
-    upper = base.encode(
-        alt.X('date:T', scale=alt.Scale(domain=brush))
-    )
+    upper = base.encode(alt.X('date:T').scale(domain=brush))
 
     lower = base.properties(
         height=60
@@ -282,8 +279,8 @@ using ``alt.repeat('layer')``:
     source = data.movies()
 
     alt.Chart(source).mark_line().encode(
-        x=alt.X("IMDB_Rating", bin=True),
-        y=alt.Y(alt.repeat('layer'), aggregate='mean', title="Mean of US and Worldwide Gross"),
+        x=alt.X("IMDB_Rating").bin(),
+        y=alt.Y(alt.repeat('layer')).aggregate('mean').title("Mean of US and Worldwide Gross"),
         color=alt.ColorDatum(alt.repeat('layer'))
     ).repeat(layer=["US_Gross", "Worldwide_Gross"])
 
@@ -305,8 +302,8 @@ concatenation:
 .. altair-plot::
 
     import altair as alt
-    from altair.expr import datum
     from vega_datasets import data
+
     iris = data.iris.url
 
     base = alt.Chart(iris).mark_point().encode(
@@ -320,7 +317,7 @@ concatenation:
 
     chart = alt.hconcat()
     for species in ['setosa', 'versicolor', 'virginica']:
-        chart |= base.transform_filter(datum.species == species)
+        chart |= base.transform_filter(alt.datum.species == species)
     chart
 
 As with the manual approach to :ref:`repeat-chart`, this is straightforward,

doc/user_guide/customization.rst

@@ -134,7 +134,7 @@ By default an Altair chart does not have a title, as seen in this example.
 
    alt.Chart(iowa).mark_area().encode(
        x="year:T",
-       y=alt.Y("net_generation:Q", stack="normalize"),
+       y=alt.Y("net_generation:Q").stack("normalize"),
        color="source:N"
    )
 
@@ -144,7 +144,7 @@ You can add a simple title by passing the `title` keyword argument with the data
 
    alt.Chart(iowa, title="Iowa's green energy boom").mark_area().encode(
        x="year:T",
-       y=alt.Y("net_generation:Q", stack="normalize"),
+       y=alt.Y("net_generation:Q").stack("normalize"),
        color="source:N"
    )
 
@@ -160,7 +160,7 @@ It is also possible to add a subtitle by passing in an `alt.Title` object.
       )
    ).mark_area().encode(
        x="year:T",
-       y=alt.Y("net_generation:Q", stack="normalize"),
+       y=alt.Y("net_generation:Q").stack("normalize"),
        color="source:N"
    )
 
@@ -176,7 +176,7 @@ The subtitle can run to two lines by passing a list where each list item is a li
       )
    ).mark_area().encode(
        x="year:T",
-       y=alt.Y("net_generation:Q", stack="normalize"),
+       y=alt.Y("net_generation:Q").stack("normalize"),
        color="source:N"
    )
 
@@ -195,7 +195,7 @@ The ``Title`` object can also configure a number of other attributes, e.g., the
       )
    ).mark_area().encode(
        x="year:T",
-       y=alt.Y("net_generation:Q", stack="normalize"),
+       y=alt.Y("net_generation:Q").stack("normalize"),
        color="source:N"
    )
 
@@ -226,9 +226,7 @@ in quantitative axes; if you would like to turn this off, you can add a
 .. altair-plot::
 
     alt.Chart(cars).mark_point().encode(
-        alt.X('Acceleration:Q',
-            scale=alt.Scale(zero=False)
-        ),
+        alt.X('Acceleration:Q').scale(zero=False),
         y='Horsepower:Q'
     )
 
@@ -237,9 +235,7 @@ To specify exact axis limits, you can use the ``domain`` property of the scale:
 .. altair-plot::
 
     alt.Chart(cars).mark_point().encode(
-        alt.X('Acceleration:Q',
-            scale=alt.Scale(domain=(5, 20))
-        ),
+        alt.X('Acceleration:Q').scale(domain=(5, 20)),
         y='Horsepower:Q'
     )
 
@@ -250,9 +246,7 @@ the ``"clip"`` property of the mark to True:
 .. altair-plot::
 
     alt.Chart(cars).mark_point(clip=True).encode(
-        alt.X('Acceleration:Q',
-            scale=alt.Scale(domain=(5, 20))
-        ),
+        alt.X('Acceleration:Q').scale(domain=(5, 20)),
         y='Horsepower:Q'
     )
 
@@ -262,12 +256,7 @@ limit to the edge of the domain:
 .. altair-plot::
 
     alt.Chart(cars).mark_point().encode(
-        alt.X('Acceleration:Q',
-            scale=alt.Scale(
-                domain=(5, 20),
-                clamp=True
-            )
-        ),
+        alt.X('Acceleration:Q').scale(domain=(5, 20), clamp=True),
         y='Horsepower:Q'
     ).interactive()
 
@@ -301,17 +290,17 @@ the y labels as a dollar value:
 .. altair-plot::
 
    alt.Chart(df).mark_circle().encode(
-       x=alt.X('x', axis=alt.Axis(format='%', title='percentage')),
-       y=alt.Y('y', axis=alt.Axis(format='$', title='dollar amount'))
+       alt.X('x').axis(format='%').title('percentage'),
+       alt.Y('y').axis(format='$').title('dollar amount')
    )
 
 Axis labels can also be easily removed:
 
 .. altair-plot::
 
    alt.Chart(df).mark_circle().encode(
-       x=alt.X('x', axis=alt.Axis(labels=False)),
-       y=alt.Y('y', axis=alt.Axis(labels=False))
+       alt.X('x').axis(labels=False),
+       alt.Y('y').axis(labels=False)
    )
 
 Additional formatting codes are available; for a listing of these see the
@@ -350,7 +339,7 @@ The legend option on all of them expects a :class:`Legend` object as its input,
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species', legend=alt.Legend(title="Species by color"))
+      color=alt.Color('species').title("Species by color")
   )
 
 Another thing you can do is move the legend to another position with the `orient` argument.
@@ -365,7 +354,7 @@ Another thing you can do is move the legend to another position with the `orient
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species', legend=alt.Legend(orient="left")),
+      color=alt.Color('species').legend(orient="left")
   )
 
 You can remove the legend entirely by submitting a null value.
@@ -380,7 +369,7 @@ You can remove the legend entirely by submitting a null value.
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species', legend=None),
+      color=alt.Color('species').legend(None),
   )
 
 Removing the Chart Border
@@ -453,8 +442,8 @@ combining the above option with setting ``axis`` to ``None`` during encoding.
     iris = data.iris()
 
     alt.Chart(iris).mark_point().encode(
-        alt.X('petalWidth', axis=None),
-        alt.Y('petalLength', axis=None),
+        alt.X('petalWidth').axis(None),
+        alt.Y('petalLength').axis(None),
         color='species'
     ).configure_axis(
         grid=False
@@ -491,7 +480,7 @@ can be passed to the `scheme` argument of the :class:`Scale` class:
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species', scale=alt.Scale(scheme='dark2'))
+      color=alt.Color('species').scale(scheme='dark2')
   )
 
 Color Domain and Range
@@ -513,7 +502,7 @@ values and colors respectively.
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species', scale=alt.Scale(domain=domain, range=range_))
+      color=alt.Color('species').scale(domain=domain, range=range_)
   )
 
 Raw Color Values
@@ -537,7 +526,7 @@ you can set ``scale=None`` to use those colors directly:
       size=100
   ).encode(
       x='x',
-      color=alt.Color('color', scale=None)
+      color=alt.Color('color').scale(None)
   )
 
 Adjusting the Width of Bar Marks