Merge pull request #4 from hanjinliu/docs-scaling

Fix autoscaling and error bars

docs/_scripts/_screenshots.py

@@ -27,7 +27,10 @@ def _write_image(src: str, ns: dict, dest: str) -> None:
             f"Error evaluating code\n\n{src}\n\nfor {dest!r}"
         ) from e
 
-    canvas = ns["canvas"]
+    if isinstance(ns.get("grid", None), CanvasGrid):
+        canvas = ns["grid"]
+    else:
+        canvas = ns["canvas"]
     assert isinstance(canvas, (CanvasGrid, SingleCanvas)), type(canvas)
     with mkdocs_gen_files.open(dest, "wb") as f:
         plt.tight_layout()
@@ -43,6 +46,7 @@ def main() -> None:
         theme.canvas_size = (800, 560)
         theme.font.size = 18
     plt.switch_backend("Agg")
+    names_found = set[str]()
     for mdfile in sorted(DOCS.rglob("*.md"), reverse=True):
         if mdfile.name in EXCLUDE:
             continue
@@ -55,15 +59,18 @@ def main() -> None:
             if code.startswith("#!skip"):
                 continue
             elif code.startswith("#!name:"):
-                if code.endswith("canvas.show()"):
+                if code.endswith(("canvas.show()", "grid.show()")):
                     code = code[:-7]
                 line = code.split("\n", 1)[0]
                 assert line.startswith("#!name:")
                 name = line.split(":", 1)[1].strip()
+                if name in names_found:
+                    raise ValueError(f"Duplicate name {name!r} in {mdfile}")
                 dest = f"_images/{name}.png"
                 _write_image(code, namespace, dest)
+                names_found.add(name)
             else:
-                if code.endswith("canvas.show()"):
+                if code.endswith(("canvas.show()", "grid.show()")):
                     code = code[:-7]
                 try:
                     exec(code, namespace, namespace)

docs/canvas/grid.md

@@ -1,66 +1,76 @@
 # Canvas Grid
 
+A "canvas grid" is a grid of canvases (which is called "figure" in `matplotlib`).
+A grid is composed of multiple canvas objects, so that grid itself does not have
+either layers or the `add_*` methods.
+
+Once a grid is created, you can add chid canvases using the `add_canvas` method.
+The signature of the method differs between 1D and 2D grid.
+
 ## Vertical/Horizontal Grid
 
 ``` python
 #!name: canvas_grid_vertical
 from whitecanvas import vgrid
 
-canvas = vgrid(3, backend="matplotlib")
+grid = vgrid(3, backend="matplotlib")
 
-c0 = canvas.add_canvas(0)
+c0 = grid.add_canvas(0)
 c0.add_text(0, 0, "Canvas 0")
-c1 = canvas.add_canvas(1)
+c1 = grid.add_canvas(1)
 c1.add_text(0, 0, "Canvas 1")
-c2 = canvas.add_canvas(2)
+c2 = grid.add_canvas(2)
 c2.add_text(0, 0, "Canvas 2")
-canvas.show()
+grid.show()
 ```
 
 
 ``` python
 #!name: canvas_grid_horizontal
 from whitecanvas import hgrid
 
-canvas = hgrid(3, backend="matplotlib")
+grid = hgrid(3, backend="matplotlib")
 
-c0 = canvas.add_canvas(0)
+c0 = grid.add_canvas(0)
 c0.add_text(0, 0, "Canvas 0")
-c1 = canvas.add_canvas(1)
+c1 = grid.add_canvas(1)
 c1.add_text(0, 0, "Canvas 1")
-c2 = canvas.add_canvas(2)
+c2 = grid.add_canvas(2)
 c2.add_text(0, 0, "Canvas 2")
-canvas.show()
+grid.show()
 ```
 
 ## 2D Grid
 
 ``` python
 #!name: canvas_grid_2d
-from whitecanvas import grid
+from whitecanvas import grid as grid2d
 
-canvas = grid(2, 2, backend="matplotlib")
+grid = grid2d(2, 2, backend="matplotlib")
 
 for i, j in [(0, 0), (0, 1), (1, 0), (1, 1)]:
-    c = canvas.add_canvas(i, j)
+    c = grid.add_canvas(i, j)
     c.add_text(0, 0, f"Canvas ({i}, {j})")
-canvas.show()
+grid.show()
 ```
 
 ## Non-uniform Grid
 
 The `*_nonuniform` functions allow you to create a grid with non-uniform sizes.
 Instead of specifying the number of rows and columns, these functions take a list of size ratios.
 
+!!! note
+    This feature is work in progress. Some backends does not support it yet.
+
 ``` python
 #!name: canvas_grid_2d_nonuniform
 
 from whitecanvas import grid_nonuniform
 
-canvas = grid_nonuniform([1, 2], [2, 1], backend="matplotlib")
+grid = grid_nonuniform([1, 2], [2, 1], backend="matplotlib")
 
 for i, j in [(0, 0), (0, 1), (1, 0), (1, 1)]:
-    c = canvas.add_canvas(i, j)
+    c = grid.add_canvas(i, j)
     c.add_text(0, 0, f"Canvas ({i}, {j})")
-canvas.show()
+grid.show()
 ```

docs/canvas/namespaces.md

@@ -4,7 +4,7 @@ Each canvas has several namespaces to control the appearance of the canvas. Firs
 all, the x/y-axis properties are controlled by the `x` and `y` namespaces.
 
 ``` python
-#!name: xy_axis_properties
+#!name: namespace_axis
 from whitecanvas import new_canvas
 
 canvas = new_canvas(backend="matplotlib")
@@ -21,7 +21,7 @@ canvas.show()
 You can set x/y labels using the `label` property.
 
 ``` python
-#!name: xy_axis_0
+#!name: namespace_axis_label_0
 from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")
@@ -35,7 +35,7 @@ The `label` property is actually another namespace. You can specify the text, fo
 etc. separately.
 
 ``` python
-#!name: xy_axis_1
+#!name: namespace_axis_label_1
 canvas = new_canvas("matplotlib")
 
 canvas.x.label.text = "X axis"
@@ -50,7 +50,7 @@ canvas.show()
 The tick properties can be set via `ticks` property.
 
 ``` python
-#!name: xy_axis_2
+#!name: namespace_ticks
 from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")
@@ -65,7 +65,7 @@ canvas.show()
 You can also override or reset the tick labels.
 
 ``` python
-#!name: xy_axis_3
+#!name: namespace_xticks_labels
 from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")
@@ -80,7 +80,7 @@ canvas.show()
 Canvas title can be set via the `title` namespace.
 
 ``` python
-#!name: xy_axis_2
+#!name: namespace_title
 from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")

docs/layers/face_layers.md

@@ -29,40 +29,52 @@ arguments. You can use the `with_edge` method of the output layer to set edge
 properties. This separation is very helpful to prevent the confusion of the arguments,
 especially the colors.
 
+Following example uses [`add_bars`][whitecanvas.canvas.CanvasBase.add_bars] and
+[`add_spans`][whitecanvas.canvas.CanvasBase.add_spans] methods to create `Bars` and
+`Spans` layers.
+
 ``` python
 #!name: face_layers_with_edge
 import numpy as np
 from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")
 
-layer = canvas.add_markers(np.arange(10), color="yellow").with_edge(color="black")
+bars_layer = (
+    canvas
+    .add_bars([0, 1, 2, 3], [3, 4, 1, 2], color="yellow")
+    .with_edge(color="black")
+)
+
+spans_layer = (
+    canvas
+    .add_spans([[0.2, 0.8], [1.4, 2.1], [1.8, 3.0]], color="blue")
+    .with_edge(color="black")
+)
+canvas.y.lim = (0, 5)
 canvas.show()
 ```
 
 All the properties can be set via properties of `face` and `edge`, or the `update`
 method.
 
 ``` python
-layer.face.color = "yellow"
-layer.face.hatch = "x"
+#!skip
+bars_layer.face.color = "yellow"
+bars_layer.face.hatch = "x"
 
-layer.edge.color = "black"
-layer.edge.width = 2
-layer.edge.style = "--"
+spans_layer.edge.color = "black"
+spans_layer.edge.width = 2
+spans_layer.edge.style = "--"
 
 # use `update`
-layer.face.update(color="yellow", hatch="x")
-layer.edge.update(color="black", width=2, style="--")
+bars_layer.face.update(color="yellow", hatch="x")
+spans_layer.edge.update(color="black", width=2, style="--")
 ```
 
-## Multi-faces and Multi-edges
-
-`Markers` and `Bars` supports multi-faces and multi-edges. This means that you can
-create a layer with multiple colors, widths, etc.
+## Multi-face and Multi-edge
 
-To do this, you have to call `with_face_multi` or `with_edge_multi` method.
-Here's an example of `Markers` with multi-faces.
+As for [`Markers`](markers.md), `Bars` and `Spans` supports multi-face and multi-edge.
 
 ``` python
 #!name: face_layers_multifaces
@@ -71,10 +83,10 @@ from whitecanvas import new_canvas
 
 canvas = new_canvas("matplotlib")
 
-layer = canvas.add_markers(
-    np.arange(10),
-).with_face_multi(
-    color=np.random.random((10, 3)),  # random colors
+layer = (
+    canvas
+    .add_bars([0, 1, 2, 3], [3, 4, 1, 2])
+    .with_face_multi(color=["red", "#00FF00", "rgb(0, 0, 255)", "black"])
 )
 canvas.show()
 ```