Improve encoding section

altair/sphinxext/schematable.py

@@ -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
 
@@ -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]
@@ -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):

doc/user_guide/configuration.rst

@@ -286,144 +286,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/

doc/user_guide/customization.rst

@@ -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/

doc/user_guide/data.rst

@@ -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