v2-docs: Add pre transform and chart state docs (#534)

* Document pre_transform_spec

* Document pre_transform_extract

* Support maxbins property as expression

* Add chart state documentation

* fmt

* fix example

* fix test

docs/source/chart_state.md

@@ -0,0 +1,15 @@
+# Chart State
+
+The Chart State workflow can be used to support interactive charts with transforms that are updated interactively. For example, for a chart that implements crossfiltering the `filter` transform must be re-evaluated repeatedly against the input dataset. 
+
+This is the foundation of Vega-Altair's [JupyterChart](https://altair-viz.github.io/user_guide/jupyter_chart.html) when combined with the [``"vegafusion"`` data transformer](https://altair-viz.github.io/user_guide/large_datasets.html#vegafusion-data-transformer).
+
+## Python
+```{eval-rst}
+.. automethod:: vegafusion.runtime.VegaFusionRuntime.new_chart_state
+```
+
+**Example**: See [chart_state.py](https://github.com/vega/vegafusion/tree/v2/examples/python-examples/chart_state.py) for a complete example.
+
+## Rust
+See [chart_state.rs](https://github.com/vega/vegafusion/tree/v2/examples/rust-examples/examples/chart_state.rs) for a complete example.

docs/source/index.md

@@ -18,5 +18,8 @@ If you've arrived here looking for information on how to scale Vega-Altair visua
 :caption: Contents
 
 column_usage
-transformed_data
+transform_data
+transform_spec
+transform_extract
+chart_state
 ```

docs/source/transform_extract.md

@@ -0,0 +1,15 @@
+# Transform Extract
+
+The `pre_transform_extract` method generates a transformed spec like the [`pre_transform_spec`](./transform_spec.md) method, but instead of inlining the transformed datasets in the spec, these datasets are returned separately in arrow table format. This can be useful in contexts where the inline datasets are large, and it's possible to transmit them more efficiently in arrow format. 
+
+## Python
+
+```{eval-rst}
+.. automethod:: vegafusion.runtime.VegaFusionRuntime.pre_transform_extract
+```
+
+**Example**: See [pre_transform_extract.py](https://github.com/vega/vegafusion/tree/v2/examples/python-examples/pre_transform_extract.py) for a complete example.
+
+## Rust
+
+See [pre_transform_extract.rs](https://github.com/vega/vegafusion/tree/v2/examples/rust-examples/examples/pre_transform_extract.rs) for a complete example.

docs/source/transform_spec.md

@@ -0,0 +1,21 @@
+# Transformed Spec
+
+VegaFusion can be used to evaluate datasets in a Vega spec, remove unused columns, and inline the results in a transformed Vega spec. This transformed Vega spec is self-contained and may be displayed with the standard Vega JavaScript library.
+
+This is the foundation of Vega-Altair's [``"vegafusion"`` data transformer](https://altair-viz.github.io/user_guide/large_datasets.html#vegafusion-data-transformer) when used with the default HTML or static image renderers. 
+
+:::{warning}
+The pre-transform process will, by default, preserve the interactive behavior of the input Vega specification. For interactive charts that perform filtering, this may result in the generation of a spec containing the full input dataset. If interactivity does not need to be preserved (e.g. if the resulting chart is used in a static context) then the ``preserve_interactivity`` option should be set to False. If interactivity is needed, then the Chart State workflow may be more appropriate.
+:::
+
+## Python
+
+```{eval-rst}
+.. automethod:: vegafusion.runtime.VegaFusionRuntime.pre_transform_spec
+```
+
+**Example**: See [pre_transform_spec.py](https://github.com/vega/vegafusion/tree/v2/examples/python-examples/pre_transform_spec.py) for a complete example.
+
+## Rust
+
+See [pre_transform_spec.rs](https://github.com/vega/vegafusion/tree/v2/examples/rust-examples/examples/pre_transform_spec.rs) for a complete example.