Improve documentation

Author: martinRenou

docs/source/api.rst

@@ -0,0 +1,16 @@
+API Reference
+=============
+
+Note that because we are exposing the Web Canvas API, you can find more tutorials and documentation following this link: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API
+
+There are some API differences though:
+
+- The Canvas widget is directly exposing the `CanvasRenderingContext2D <https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D>`_ API
+- All the API is written in *snake_case* instead of *camelCase*, so for example ``canvas.fillStyle = 'red'`` in JavaScript becomes ``canvas.fill_style = 'red'`` in Python
+- The Canvas widget exposes a ``clear`` method, ``canvas.clear()`` is a shortcut for ``canvas.clear_rect(0, 0, canvas.size[0], canvas.size[1])``
+- We provide a `hold_canvas` context manager if you want to perform lots of commands at once
+- The Web canvas putImageData method does not support transparency and the current transformation state, our ``Canvas.put_image_data`` does support them!
+
+
+.. automodule:: ipycanvas.canvas
+   :members:

docs/source/conf.py

@@ -3,10 +3,10 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     # 'sphinx.ext.intersphinx',
     # 'sphinx.ext.autosummary',
     # 'sphinx.ext.viewcode',
-    # 'sphinx.ext.napoleon',
     # 'jupyter_sphinx.embed_widgets',
 ]
 
@@ -28,3 +28,5 @@
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 htmlhelp_basename = 'ipycanvasdoc'
+
+autodoc_member_order = 'bysource'

docs/source/index.rst

@@ -1,8 +1,22 @@
 ipycanvas: Jupyter Interactive Widgets library exposing the browser's Canvas API
 ================================================================================
 
+Try it online:
+--------------
+
+You can try ipycanvas, without the need of installing anything on your computer, using `mybinder <https://mybinder.org/>`_ by clicking on this badge:
+
+.. image:: https://img.shields.io/badge/start-drawing!-F5A252.svg?logo=data:image/png;base64,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
+   :target: https://mybinder.org/v2/gh/martinRenou/ipycanvas/stable?filepath=examples
+
 .. toctree::
     :caption: Installation
     :maxdepth: 2
 
     installation
+
+
+.. toctree::
+    :caption: API Reference
+
+    api

ipycanvas/canvas.py

@@ -16,12 +16,17 @@
 
 
 def to_camel_case(snake_str):
-    """Turn a snake_case string into a camelCase one."""
     components = snake_str.split('_')
     return components[0] + ''.join(x.title() for x in components[1:])
 
 
 class Canvas(DOMWidget):
+    """Create a Canvas widget.
+
+    Args:
+        size (tuple): The size (in pixels) of the canvas
+    """
+
     _model_name = Unicode('CanvasModel').tag(sync=True)
     _model_module = Unicode(module_name).tag(sync=True)
     _model_module_version = Unicode(module_version).tag(sync=True)
@@ -31,15 +36,33 @@ class Canvas(DOMWidget):
 
     size = Tuple((700, 500), help='Size of the Canvas, this is not equal to the size of the view').tag(sync=True)
 
+    #: (valid HTML color) The color for filling rectangles and paths. Default to ``'black'``.
     fill_style = Color('black')
+
+    #: (valid HTML color) The color for rectangles and paths stroke. Default to ``'black'``.
     stroke_style = Color('black')
+
+    #: (float) Transparency level. Default to ``1.0``.
     global_alpha = Float(1.0)
 
+    #: (str) Font for the text rendering. Default to ``'12px serif'``.
     font = Unicode('12px serif')
-    text_align = Unicode('start')
-    text_baseline = Unicode('alphabetic')
-    direction = Unicode('inherit')
 
+    #: (str) Text alignment, possible values are ``'start'``, ``'end'``, ``'left'``, ``'right'``, and ``'center'``.
+    #: Default to ``'start'``.
+    text_align = Enum(['start', 'end', 'left', 'right', 'center'], default_value='start')
+
+    #: (str) Text baseline, possible values are ``'top'``, ``'hanging'``, ``'middle'``, ``'alphabetic'``, ``'ideographic'``
+    #: and ``'bottom'``.
+    #: Default to ``'alphabetic'``.
+    text_baseline = Enum(['top', 'hanging', 'middle', 'alphabetic', 'ideographic', 'bottom'], default_value='alphabetic')
+
+    #: (str) Text direction, possible values are ``'ltr'``, ``'rtl'``, and ``'inherit'``.
+    #: Default to ``'inherit'``.
+    direction = Enum(['ltr', 'rtl', 'inherit'], default_value='inherit')
+
+    #: (str) Global composite operation, possible values are listed below:
+    #: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Compositing#globalCompositeOperation
     global_composite_operation = Enum(
         ['source-over', 'source-in', 'source-out', 'source-atop',
          'destination-over', 'destination-in', 'destination-out',
@@ -62,21 +85,17 @@ def __init__(self, *args, **kwargs):
 
     # Rectangles methods
     def fill_rect(self, x, y, width, height):
-        """Draw a filled rectangle."""
+        """Draw a filled rectangle of size ``(width, height)`` at the ``(x, y)`` position."""
         self._send_canvas_command('fillRect', (x, y, width, height))
 
     def stroke_rect(self, x, y, width, height):
-        """Draw a rectangular outline."""
+        """Draw a rectangular outline of size ``(width, height)`` at the ``(x, y)`` position."""
         self._send_canvas_command('strokeRect', (x, y, width, height))
 
     def clear_rect(self, x, y, width, height):
-        """Clear the specified rectangular area, making it fully transparent."""
+        """Clear the specified rectangular area of size ``(width, height)`` at the ``(x, y)`` position, making it fully transparent."""
         self._send_canvas_command('clearRect', (x, y, width, height))
 
-    def rect(self, x, y, width, height):
-        """Draw a rectangle whose top-left corner is specified by (x, y) with the specified width and height."""
-        self._send_canvas_command('rect', (x, y, width, height))
-
     # Paths methods
     def begin_path(self):
         """Call this method when you want to create a new path."""
@@ -91,35 +110,42 @@ def close_path(self):
         self._send_canvas_command('closePath')
 
     def stroke(self):
-        """Stroke (outlines) the current path with the current stroke style."""
+        """Stroke (outlines) the current path with the current ``stroke_style``."""
         self._send_canvas_command('stroke')
 
     def fill(self):
-        """Fill the current or given path with the current fillStyle."""
+        """Fill the current or given path with the current ``fill_style``."""
         self._send_canvas_command('fill')
 
     def move_to(self, x, y):
-        """Move the "pen" to the given (x, y) coordinates."""
+        """Move the "pen" to the given ``(x, y)`` coordinates."""
         self._send_canvas_command('moveTo', (x, y))
 
     def line_to(self, x, y):
-        """Add a straight line to the current path by connecting the path's last point to the specified (x, y) coordinates.
+        """Add a straight line to the current path by connecting the path's last point to the specified ``(x, y)`` coordinates.
 
         Like other methods that modify the current path, this method does not directly render anything. To
         draw the path onto the canvas, you can use the fill() or stroke() methods.
         """
         self._send_canvas_command('lineTo', (x, y))
 
+    def rect(self, x, y, width, height):
+        """Draw a rectangle of size ``(width, height)`` at the ``(x, y)`` position in the current path."""
+        self._send_canvas_command('rect', (x, y, width, height))
+
     def arc(self, x, y, radius, start_angle, end_angle, anticlockwise=False):
-        """Create a circular arc centered at (x, y) with a radius of radius.
+        """Create a circular arc centered at ``(x, y)`` with a radius of ``radius``.
 
-        The path starts at startAngle and ends at endAngle, and travels in the direction given by
-        anticlockwise (defaulting to clockwise).
+        The path starts at ``start_angle`` and ends at ``end_angle``, and travels in the direction given by
+        ``anticlockwise`` (defaulting to clockwise: ``False``).
         """
         self._send_canvas_command('arc', (x, y, radius, start_angle, end_angle, anticlockwise))
 
     def arc_to(self, x1, y1, x2, y2, radius):
-        """Add a circular arc to the current path, using the given control points and radius."""
+        """Add a circular arc to the current path.
+
+        Using the given control points ``(x1, y1)`` and ``(x2, y2)`` and the ``radius``.
+        """
         self._send_canvas_command('arcTo', (x1, y1, x2, y2, radius))
 
     def quadratic_curve_to(self, cp1x, cp1y, x, y):
@@ -142,11 +168,11 @@ def bezier_curve_to(self, cp1x, cp1y, cp2x, cp2y, x, y):
 
     # Text methods
     def fill_text(self, text, x, y, max_width=None):
-        """Fill a given text at the given (x,y) position. Optionally with a maximum width to draw."""
+        """Fill a given text at the given ``(x, y)`` position. Optionally with a maximum width to draw."""
         self._send_canvas_command('fillText', (text, x, y, max_width))
 
     def stroke_text(self, text, x, y, max_width=None):
-        """Stroke a given text at the given (x,y) position. Optionally with a maximum width to draw."""
+        """Stroke a given text at the given ``(x, y)`` position. Optionally with a maximum width to draw."""
         self._send_canvas_command('strokeText', (text, x, y, max_width))
 
     # Image methods
@@ -264,6 +290,13 @@ def _send_command(self, command, buffers=[]):
 
 
 class MultiCanvas(DOMWidget):
+    """Create a MultiCanvas widget with n_canvases Canvas widgets.
+
+    Args:
+        n_canvases (int): The number of canvases to create
+        size (tuple): The size (in pixels) of the canvases
+    """
+
     _model_name = Unicode('MultiCanvasModel').tag(sync=True)
     _model_module = Unicode(module_name).tag(sync=True)
     _model_module_version = Unicode(module_version).tag(sync=True)
@@ -276,7 +309,7 @@ class MultiCanvas(DOMWidget):
     _canvases = List(Instance(Canvas)).tag(sync=True, **widget_serialization)
 
     def __init__(self, n_canvases=3, *args, **kwargs):
-        """Create a MultiCanvas widget with n_canvases Canvas widgets."""
+        """Constructor."""
         size = kwargs.get('size', (700, 500))
 
         super(MultiCanvas, self).__init__(*args, _canvases=[Canvas(size=size) for _ in range(n_canvases)], **kwargs)
@@ -295,7 +328,13 @@ def _on_size_change(self, change):
 
 @contextmanager
 def hold_canvas(canvas):
-    """Hold any drawing on the canvas, and perform only one draw command at the end."""
+    """Hold any drawing on the canvas, and perform all commands in a single shot at the end.
+
+    This is way more efficient than sending commands one by one.
+
+    Args:
+        canvas (ipycanvas.canvas.Canvas): The canvas widget on which to hold the commands
+    """
     canvas.caching = True
     yield
     canvas.flush()