Merge pull request #157 from martinRenou/docs

Docs

Author: martinRenou

docs/source/canvas_state.rst

@@ -1,8 +1,10 @@
 Canvas state
 ============
 
-- ``save()``: Saves the entire state of the canvas.
-- ``restore()``: Restores the most recently saved canvas state.
+- ``save()``:
+    Saves the entire state of the canvas.
+- ``restore()``:
+    Restores the most recently saved canvas state.
 
 Canvas states are stored on a stack. Every time the ``save()`` method is called, the current drawing state is pushed onto the stack. A drawing state consists of:
 

docs/source/conf.py

@@ -31,6 +31,8 @@
     'goatcounter.js'
 ]
 
+html_static_path = ['_static']
+
 html_css_files = [
     'custom.css'
 ]

docs/source/drawing_images.rst

@@ -6,7 +6,9 @@ From an Image widget
 
 You can draw from an `Image <https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html#Image>`_ widget directly, this is the less optimized solution but it works perfectly fine if you don't draw more than a hundred images at a time.
 
-- ``draw_image(image, x=0, y=0, width=None, height=None)``: Draw an ``image`` on the Canvas at the coordinates (``x``, ``y``) and scale it to (``width``, ``height``). The ``image`` must be an ``Image`` widget or another ``Canvas``. If ``width``/``height`` is ``None``, the natural image ``width``/``height`` is used.
+- ``draw_image(image, x=0, y=0, width=None, height=None)``:
+    Draw an ``image`` on the Canvas at the coordinates (``x``, ``y``) and scale it to (``width``, ``height``).
+    The ``image`` must be an ``Image`` widget or another ``Canvas``. If ``width``/``height`` is ``None``, the natural image ``width``/``height`` is used.
 
 .. code:: Python
 
@@ -51,7 +53,9 @@ From a NumPy array
 
 You can directly draw a NumPy array of pixels on the ``Canvas``, it must be a 3-D array of integers and the last dimension must be 3 or 4 (rgb or rgba), with values going from ``0`` to ``255``.
 
-- ``put_image_data(image_data, x=0, y=0)``: Draw an image on the Canvas. ``image_data`` should be  a NumPy array containing the image to draw and ``x`` and ``y`` the pixel position where to draw (top left pixel of the image).
+- ``put_image_data(image_data, x=0, y=0)``:
+    Draw an image on the Canvas. ``image_data`` should be  a NumPy array containing the image to
+    draw and ``x`` and ``y`` the pixel position where to draw (top left pixel of the image).
 
 .. code:: python
 

docs/source/drawing_paths.rst

@@ -54,11 +54,15 @@ extra steps:
 
 Here are the functions used to perform these steps:
 
-- ``begin_path()``: Creates a new path. Once created, future drawing commands are directed into the path and used to build the path up.
+- ``begin_path()``:
+  Creates a new path. Once created, future drawing commands are directed into the path and used to build the path up.
 - Path commands like ``line_to`` and ``arc``
-- ``close_path()``: Adds a straight line to the path, going to the start of the current path.
-- ``stroke()``: Draws the shape by stroking its outline.
-- ``fill(rule)``: Draws a solid shape by filling the path's content area. The given fill rule is applied, possible rules are `nonzero` and `evenodd`.
+- ``close_path()``:
+  Adds a straight line to the path, going to the start of the current path.
+- ``stroke()``:
+  Draws the shape by stroking its outline.
+- ``fill(rule)``:
+  Draws a solid shape by filling the path's content area. The given fill rule is applied, possible rules are `nonzero` and `evenodd`.
 
 .. code:: Python
 
@@ -83,20 +87,28 @@ Path commands
 
 Here are the available draw commands:
 
-- ``move_to(x, y)``: Moves the pen to the coordinates specified by x and y. This does not actually draw anything.
-- ``line_to(x, y)``: Add a straight line to the current path by connecting the path’s last point to the specified (x, y) coordinates.
-- ``arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``: Add a circular arc centered at (x, y) with a radius
+- ``move_to(x, y)``:
+  Moves the pen to the coordinates specified by x and y. This does not actually draw anything.
+- ``line_to(x, y)``:
+  Add a straight line to the current path by connecting the path’s last point to the specified (x, y) coordinates.
+- ``arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``:
+  Add a circular arc centered at (x, y) with a radius
   of ``radius`` to the current path. The path starts at ``start_angle`` and ends at ``end_angle`` in radians, and travels in the direction given by
   ``anticlockwise`` (defaulting to clockwise: False).
-- ``arc_to(x1, y1, x2, y2, radius)``: Add a circular arc to the current path. Using the given control points (``x1``, ``y1``)
+- ``arc_to(x1, y1, x2, y2, radius)``:
+  Add a circular arc to the current path. Using the given control points (``x1``, ``y1``)
   and (``x2``, ``y2``) and the ``radius``.
-- ``ellipse(x, y, radius_x, radius_y, rotation, start_angle, end_angle, anticlockwise=False)``: Add an ellipse centered at ``(x, y)`` with
+- ``ellipse(x, y, radius_x, radius_y, rotation, start_angle, end_angle, anticlockwise=False)``:
+  Add an ellipse centered at ``(x, y)`` with
   the radii ``radius_x`` and ``radius_y`` to the current path.
-- ``quadratic_curve_to(cp1x, cp1y, x, y)``: Add a quadratic Bezier curve to the current path.
+- ``quadratic_curve_to(cp1x, cp1y, x, y)``:
+  Add a quadratic Bezier curve to the current path.
   It requires two points: the first one is a control point and the second one is the end point. The starting point is the latest point in the current path, which can be changed using ``move_to()`` before creating the quadratic Bezier curve.
-- ``bezier_curve_to(cp1x, cp1y, cp2x, cp2y, x, y)``: Add a cubic Bezier curve to the current path.
+- ``bezier_curve_to(cp1x, cp1y, cp2x, cp2y, x, y)``:
+  Add a cubic Bezier curve to the current path.
   It requires three points: the first two are control points and the third one is the end point. The starting point is the latest point in the current path, which can be changed using ``move_to()`` before creating the Bezier curve.
-- ``rect(x, y, width, height)``: Draws a rectangle whose top-left corner is specified by (``x``, ``y``) with the specified ``width`` and ``height``.
+- ``rect(x, y, width, height)``:
+  Draws a rectangle whose top-left corner is specified by (``x``, ``y``) with the specified ``width`` and ``height``.
 
 
 Examples

docs/source/drawing_shapes.rst

@@ -22,14 +22,21 @@ Drawing rectangles
 
 There are four methods that draw rectangles on the canvas:
 
-- ``fill_rect(x, y, width, height=None)``: Draws a filled rectangle. If ``height`` is None, it is set to the same value as ``width``.
-- ``stroke_rect(x, y, width, height=None)``: Draws a rectangular outline. If ``height`` is None, it is set to the same value as ``width``.
-- ``fill_rects(x, y, width, height=None)``: Draws filled rectangles. Where ``x``, ``y``, ``width`` and ``height`` are either integers, lists of integers or NumPy arrays. If ``height`` is None, it is set to the same value as ``width``.
-- ``stroke_rects(x, y, width, height=None)``: Draws rectangular outlines. Where ``x``, ``y``, ``width`` and ``height`` are either integers, lists of integers or NumPy arrays. If ``height`` is None, it is set to the same value as ``width``.
+- ``fill_rect(x, y, width, height=None)``:
+    Draws a filled rectangle. If ``height`` is None, it is set to the same value as ``width``.
+- ``stroke_rect(x, y, width, height=None)``:
+    Draws a rectangular outline. If ``height`` is None, it is set to the same value as ``width``.
+- ``fill_rects(x, y, width, height=None)``:
+    Draws filled rectangles. Where ``x``, ``y``, ``width`` and ``height`` are either integers, lists of integers or NumPy arrays.
+    If ``height`` is None, it is set to the same value as ``width``.
+- ``stroke_rects(x, y, width, height=None)``:
+    Draws rectangular outlines. Where ``x``, ``y``, ``width`` and ``height`` are either integers, lists of integers or NumPy arrays.
+    If ``height`` is None, it is set to the same value as ``width``.
 
 You can also clear a certain canvas rectangle area:
 
-- ``clear_rect(x, y, width, height=None)``: Clears the specified rectangular area, making it fully transparent. If ``height`` is None, it is set to the same value as ``width``.
+- ``clear_rect(x, y, width, height=None)``:
+    Clears the specified rectangular area, making it fully transparent. If ``height`` is None, it is set to the same value as ``width``.
 
 .. code:: Python
 
@@ -74,8 +81,10 @@ Drawing polygons
 You can draw a polygon by providing a list of points, either a Python list, or a NumPy array.
 It's the fastest way to draw a polygon with ipycanvas.
 
-- ``fill_polygon(points)``: Fill a polygon from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
-- ``stroke_polygon(points)``: Draw polygon outline from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
+- ``fill_polygon(points)``:
+    Fill a polygon from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
+- ``stroke_polygon(points)``:
+    Draw polygon outline from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
 
 .. code:: Python
 
@@ -129,15 +138,23 @@ Drawing arcs and circles
 
 There are methods that draw arcs/circles on the canvas:
 
-- ``fill_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``: Draw a filled arc centered at ``(x, y)`` with a radius of ``radius``.
-- ``stroke_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``: Draw an arc outline centered at ``(x, y)`` with a radius of ``radius``.
-- ``fill_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)``: Draw filled arcs centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` and other arguments are NumPy arrays, lists or scalar values.
-- ``stroke_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)``: Draw an arc outlines centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` and other arguments are NumPy arrays, lists or scalar values.
-
-- ``fill_circle(x, y, radius)``: Draw a filled circle centered at ``(x, y)`` with a radius of ``radius``.
-- ``stroke_circle(x, y, radius)``: Draw an circle outline centered at ``(x, y)`` with a radius of ``radius``.
-- ``fill_circles(x, y, radius)``: Draw filled circles centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` are NumPy arrays, lists or scalar values.
-- ``stroke_circles(x, y, radius)``: Draw a circle outlines centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` are NumPy arrays, lists or scalar values.
+- ``fill_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``:
+    Draw a filled arc centered at ``(x, y)`` with a radius of ``radius``.
+- ``stroke_arc(x, y, radius, start_angle, end_angle, anticlockwise=False)``:
+    Draw an arc outline centered at ``(x, y)`` with a radius of ``radius``.
+- ``fill_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)``:
+    Draw filled arcs centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` and other arguments are NumPy arrays, lists or scalar values.
+- ``stroke_arcs(x, y, radius, start_angle, end_angle, anticlockwise=False)``:
+    Draw an arc outlines centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` and other arguments are NumPy arrays, lists or scalar values.
+
+- ``fill_circle(x, y, radius)``:
+    Draw a filled circle centered at ``(x, y)`` with a radius of ``radius``.
+- ``stroke_circle(x, y, radius)``:
+    Draw an circle outline centered at ``(x, y)`` with a radius of ``radius``.
+- ``fill_circles(x, y, radius)``:
+    Draw filled circles centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` are NumPy arrays, lists or scalar values.
+- ``stroke_circles(x, y, radius)``:
+    Draw a circle outlines centered at ``(x, y)`` with a radius of ``radius``. Where ``x``, ``y``, ``radius`` are NumPy arrays, lists or scalar values.
 
 
 .. code:: Python
@@ -163,8 +180,10 @@ Drawing lines
 
 There are two commands for drawing a straight line from one point to another:
 
-- ``stroke_line(x1, y1, x2, y2)``: Draw a line from ``(x1, y1)`` to ``(x2, y2)``.
-- ``stroke_lines(points)``: Draw a path of consecutive lines from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
+- ``stroke_line(x1, y1, x2, y2)``:
+    Draw a line from ``(x1, y1)`` to ``(x2, y2)``.
+- ``stroke_lines(points)``:
+    Draw a path of consecutive lines from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
 
 .. code:: Python
 

docs/source/drawing_text.rst

@@ -3,8 +3,10 @@ Drawing text
 
 There are two methods that draw text on the canvas:
 
-- ``fill_text(text, x, y, max_width=None)``: Fills a given ``text`` at the given (``x``, ``y``) position. Optionally with a maximum width to draw.
-- ``stroke_text(text, x, y, max_width=None)``: Strokes a given ``text`` at the given (``x``, ``y``) position. Optionally with a maximum width to draw.
+- ``fill_text(text, x, y, max_width=None)``:
+    Fills a given ``text`` at the given (``x``, ``y``) position. Optionally with a maximum width to draw.
+- ``stroke_text(text, x, y, max_width=None)``:
+    Strokes a given ``text`` at the given (``x``, ``y``) position. Optionally with a maximum width to draw.
 
 .. code:: Python
 
@@ -35,10 +37,14 @@ Styles and colors
 
 You can change the text style by changing the following ``Canvas`` attributes:
 
-- ``font``: (str) The current text style being used when drawing text. This string uses the same syntax as the CSS font property. The default font is ``"12px sans-serif"``.
-- ``text_align``: (str) Text alignment setting. Possible values: ``"start"``, ``"end"``, ``"left"``, ``"right"`` or ``"center"``. The default value is ``"start"``.
-- ``text_baseline``: (str) Baseline alignment setting. Possible values: ``"top"``, ``"hanging"``, ``"middle"``, ``"alphabetic"``, ``"ideographic"``, ``"bottom"``. The default value is ``"alphabetic"``.
-- ``direction``: (str) Directionality. Possible values: ``"ltr"``, ``"rtl"``, ``"inherit"``. The default value is ``"inherit"``.
+- ``font``: (str)
+    The current text style being used when drawing text. This string uses the same syntax as the CSS font property. The default font is ``"12px sans-serif"``.
+- ``text_align``: (str)
+    Text alignment setting. Possible values: ``"start"``, ``"end"``, ``"left"``, ``"right"`` or ``"center"``. The default value is ``"start"``.
+- ``text_baseline``: (str)
+    Baseline alignment setting. Possible values: ``"top"``, ``"hanging"``, ``"middle"``, ``"alphabetic"``, ``"ideographic"``, ``"bottom"``. The default value is ``"alphabetic"``.
+- ``direction``: (str)
+    Directionality. Possible values: ``"ltr"``, ``"rtl"``, ``"inherit"``. The default value is ``"inherit"``.
 
 .. note::
     You can still use ``fill_style``, ``stroke_style``, ``shadow_color`` etc for coloring text and applying shadows.