Skip to content

Commit

Permalink
Improve encoding section (#2735)
Browse files Browse the repository at this point in the history 
* Remove key channel as not relevant for Altair and not documented anyway

* Add explanation and description to detail channel

* Add explanation on difference between datum and value

* Remove key and description also from channel option sections

* Update doc/user_guide/encoding.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encoding.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encoding.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encoding.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Fix usage of alt.value in rule example

* Move section on themes from configuration to customization page

* Collapse object tables by default

* Move encodings page into subfolder

* Move content on channels and channel options into separate subpages

* Introduce both concepts of a channel and channel options in the beginning. Other minor improvements

* Format code

* Minor language improvements

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/index.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Update doc/user_guide/encodings/channels.rst

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>

* Add reference to faceted charts section

* Add introductory sentences before tables

Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>
  • Loading branch information
@binste @joelostblom
binste and joelostblom committed Dec 19, 2022
1 parent f9dfc57 commit dfb11f5
Show file tree
Hide file tree
Showing 7 changed files with 613 additions and 459 deletions.
19 changes: 16 additions & 3 deletions altair/sphinxext/schematable.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

from docutils import nodes, utils
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives import flag
from recommonmark.parser import CommonMarkParser
from sphinx import addnodes

Expand Down Expand Up @@ -181,7 +182,7 @@ class AltairObjectTableDirective(Directive):
has_content = False
required_arguments = 1

option_spec = {"properties": validate_properties}
option_spec = {"properties": validate_properties, "dont-collapse-table": flag}

def run(self):
objectname = self.arguments[0]
Expand All @@ -191,10 +192,22 @@ def run(self):
schema = cls.resolve_references(cls._schema)

properties = self.options.get("properties", None)
dont_collapse_table = "dont-collapse-table" in self.options

result = []
if not dont_collapse_table:
html = "<details><summary><a>Click to show table</a></summary>"
raw_html = nodes.raw("", html, format="html")
result += [raw_html]
# create the table from the object
table = prepare_schema_table(schema, props=properties)
return [table]
result.append(prepare_schema_table(schema, props=properties))

if not dont_collapse_table:
html = "</details>"
raw_html = nodes.raw("", html, format="html")
result += [raw_html]

return result


def setup(app):
Expand Down
149 changes: 6 additions & 143 deletions doc/user_guide/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ Here is an example:
labelFontSize=14
)

Additional properties are summarized in the following table:

.. altair-object-table:: altair.HeaderConfig


Expand Down Expand Up @@ -205,7 +207,8 @@ the following properties:

Projection Configuration
------------------------
:meth:`Chart.configure_projection`
Projections can be configured using :meth:`Chart.configure_projection`,
which has the following properties:

.. altair-object-table:: altair.ProjectionConfig

Expand All @@ -214,7 +217,8 @@ Projection Configuration

Selection Configuration
-----------------------
:meth:`Chart.configure_selection`
Selections can be configured using :meth:`Chart.configure_selection`,
which has the following properties:

.. altair-object-table:: altair.SelectionConfig

Expand Down Expand Up @@ -286,144 +290,3 @@ Additional properties are summarized in the following table:

.. altair-object-table:: altair.ViewConfig


.. _chart-themes:

Altair Themes
-------------
Altair makes available a theme registry that lets users apply chart configurations
globally within any Python session. This is done via the ``alt.themes`` object.

The themes registry consists of functions which define a specification dictionary
that will be added to every created chart.
For example, the default theme configures the default size of a single chart:

>>> import altair as alt
>>> default = alt.themes.get()
>>> default()
{'config': {'view': {'continuousWidth': 400, 'continuousHeight': 300}}}

You can see that any chart you create will have this theme applied, and these configurations
added to its specification:

.. altair-plot::
:output: repr

import altair as alt
from vega_datasets import data

chart = alt.Chart(data.cars.url).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q'
)

chart.to_dict()

The rendered chart will then reflect these configurations:

.. altair-plot::

chart

Changing the Theme
~~~~~~~~~~~~~~~~~~
If you would like to enable any other theme for the length of your Python session,
you can call ``alt.themes.enable(theme_name)``.
For example, Altair includes a theme in which the chart background is opaque
rather than transparent:

.. altair-plot::
:output: repr

alt.themes.enable('opaque')
chart.to_dict()

.. altair-plot::

chart

Notice that the background color of the chart is now set to white.
If you would like no theme applied to your chart, you can use the
theme named ``'none'``:

.. altair-plot::
:output: repr

alt.themes.enable('none')
chart.to_dict()

.. altair-plot::

chart

Because the view configuration is not set, the chart is smaller
than the default rendering.

If you would like to use any theme just for a single chart, you can use the
``with`` statement to enable a temporary theme:

.. altair-plot::
:output: none

with alt.themes.enable('default'):
spec = chart.to_json()

Currently Altair does not offer many built-in themes, but we plan to add
more options in the future.

Defining a Custom Theme
~~~~~~~~~~~~~~~~~~~~~~~
The theme registry also allows defining and registering custom themes.
A theme is simply a function that returns a dictionary of default values
to be added to the chart specification at rendering time, which is then
registered and activated.

For example, here we define a theme in which all marks are drawn with black
fill unless otherwise specified:

.. altair-plot::

import altair as alt
from vega_datasets import data

# define the theme by returning the dictionary of configurations
def black_marks():
return {
'config': {
'view': {
'height': 300,
'width': 400,
},
'mark': {
'color': 'black',
'fill': 'black'
}
}
}

# register the custom theme under a chosen name
alt.themes.register('black_marks', black_marks)

# enable the newly registered theme
alt.themes.enable('black_marks')

# draw the chart
cars = data.cars.url
alt.Chart(cars).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q'
)


If you want to restore the default theme, use:

.. altair-plot::
:output: none

alt.themes.enable('default')


For more ideas on themes, see the `Vega Themes`_ repository.


.. _Vega Themes: https://github.com/vega/vega-themes/
142 changes: 142 additions & 0 deletions doc/user_guide/customization.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -566,3 +566,145 @@ it is rendererd, you can set ``width`` or ``height`` to the string ``"container"
Note that this will only scale with the container if its parent element has a size determined
outside the chart itself; For example, the container may be a ``<div>`` element that has style
``width: 100%; height: 300px``.


.. _chart-themes:

Chart Themes
------------
Altair makes available a theme registry that lets users apply chart configurations
globally within any Python session. This is done via the ``alt.themes`` object.

The themes registry consists of functions which define a specification dictionary
that will be added to every created chart.
For example, the default theme configures the default size of a single chart:

>>> import altair as alt
>>> default = alt.themes.get()
>>> default()
{'config': {'view': {'continuousWidth': 400, 'continuousHeight': 300}}}

You can see that any chart you create will have this theme applied, and these configurations
added to its specification:

.. altair-plot::
:output: repr

import altair as alt
from vega_datasets import data

chart = alt.Chart(data.cars.url).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q'
)

chart.to_dict()

The rendered chart will then reflect these configurations:

.. altair-plot::

chart

Changing the Theme
~~~~~~~~~~~~~~~~~~
If you would like to enable any other theme for the length of your Python session,
you can call ``alt.themes.enable(theme_name)``.
For example, Altair includes a theme in which the chart background is opaque
rather than transparent:

.. altair-plot::
:output: repr

alt.themes.enable('opaque')
chart.to_dict()

.. altair-plot::

chart

Notice that the background color of the chart is now set to white.
If you would like no theme applied to your chart, you can use the
theme named ``'none'``:

.. altair-plot::
:output: repr

alt.themes.enable('none')
chart.to_dict()

.. altair-plot::

chart

Because the view configuration is not set, the chart is smaller
than the default rendering.

If you would like to use any theme just for a single chart, you can use the
``with`` statement to enable a temporary theme:

.. altair-plot::
:output: none

with alt.themes.enable('default'):
spec = chart.to_json()

Currently Altair does not offer many built-in themes, but we plan to add
more options in the future.

Defining a Custom Theme
~~~~~~~~~~~~~~~~~~~~~~~
The theme registry also allows defining and registering custom themes.
A theme is simply a function that returns a dictionary of default values
to be added to the chart specification at rendering time, which is then
registered and activated.

For example, here we define a theme in which all marks are drawn with black
fill unless otherwise specified:

.. altair-plot::

import altair as alt
from vega_datasets import data

# define the theme by returning the dictionary of configurations
def black_marks():
return {
'config': {
'view': {
'height': 300,
'width': 400,
},
'mark': {
'color': 'black',
'fill': 'black'
}
}
}

# register the custom theme under a chosen name
alt.themes.register('black_marks', black_marks)

# enable the newly registered theme
alt.themes.enable('black_marks')

# draw the chart
cars = data.cars.url
alt.Chart(cars).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q'
)


If you want to restore the default theme, use:

.. altair-plot::
:output: none

alt.themes.enable('default')


For more ideas on themes, see the `Vega Themes`_ repository.


.. _Vega Themes: https://github.com/vega/vega-themes/
2 changes: 1 addition & 1 deletion doc/user_guide/data.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -441,7 +441,7 @@ data before usage in Altair using GeoPandas for example as such:
:hidden:

self
encoding
encodings/index
marks/index
transform/index
interactions
Expand Down

0 comments on commit dfb11f5

Please sign in to comment.