docs: improve size.md

examples/specs/bar_1d_rangestep_config.vl.json → examples/specs/bar_1d_step_config.vl.json

@@ -11,5 +11,5 @@
       "axis": {"title": "population"}
     }
   },
-  "config": {"view": {"discreteWidth": {"step": 21}}}
+  "config": {"view": {"step": 15}}
 }

examples/specs/bar_size_explicit.vl.json → examples/specs/bar_size_default.vl.json

@@ -1,7 +1,5 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v3.json",
-  "width": 120,
-  "height": 120,
   "data": {"url": "data/cars.json"},
   "mark": "bar",
   "encoding": {

examples/specs/bar_size_step_small.vl.json

@@ -1,16 +1,16 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v3.json",
-  "data": {
-    "values": [
-      {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
-      {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
-      {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
-    ]
-  },
-  "width": {"step": 11},
+  "width": {"step": 40},
+  "data": {"url": "data/cars.json"},
   "mark": "bar",
   "encoding": {
-    "x": {"field": "a", "type": "ordinal"},
-    "y": {"field": "b", "type": "quantitative"}
+    "x": {
+      "field": "Origin",
+      "type": "nominal"
+    },
+    "y": {
+      "aggregate": "count",
+      "type": "quantitative"
+    }
   }
 }

site/docs/encoding/scale.md

@@ -287,9 +287,15 @@ For example, the following bar chart has uses a band scale for its x-position.
 <a name="padding"/>
 {:#range-step}
 
-To customize the step size of band scales for x/y-fields, we can set the step property of the view's `width`/`height`:
+To customize the step size of band scales for x/y-fields, we can set the step property of the view's `width`/`height`.
 
-<span class="vl-example" data-name="step_small"></span>
+For example, we can either make a bar chart have a fixed width:
+
+<span class="vl-example" data-name="bar_size_fit"></span>
+
+or set the width per discrete step:
+
+<span class="vl-example" data-name="bar_size_step_small"></span>
 
 To customize the range of band and point scales, users can provide the following properties:
 

site/docs/spec.md

@@ -139,4 +139,8 @@ In addition, the following properties of the `view` configuration determine the
 
 {% include table.html props="continuousWidth,continuousHeight,discreteWidth,discreteHeight,step" source="ViewConfig" %}
 
+For example, setting the `step` property in the view config can adjust default discrete step in the plot.
+
+<span class="vl-example" data-name="bar_1d_step_config"></span>
+
 **For more information about view size, please see the [size](size.html) documentation.**