Add .pyi files with more comprehensive docstrings (#10)

This both improves the API documentation, and allows IDEs to type hint
better.

.github/workflows/build_docs.yaml

@@ -20,7 +20,7 @@ jobs:
     - name: Build HTML documentation with Sphinx
       run: |
         make html
-        make html SPHINXOPTS="-W --keep-going -n"
+        make html SPHINXOPTS="-W --keep-going"
       working-directory: docs
     - uses: actions/upload-pages-artifact@v3
       with:

.github/workflows/check_docs.yaml

@@ -18,7 +18,7 @@ jobs:
     - name: Build HTML documentation with Sphinx
       run: |
         make html
-        make html SPHINXOPTS="-W --keep-going -n"
+        make html SPHINXOPTS="-W --keep-going"
       working-directory: docs
     - uses: actions/upload-artifact@v4
       with:

docs/source/conf.py

@@ -17,6 +17,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
     'autoapi.extension'
 ]
 
@@ -26,7 +27,8 @@
 # -- Options for intersphinx -------------------------------------------------
 
 intersphinx_mapping = {
-    'micropython': ('https://docs.micropython.org/en/latest', None)
+    'micropython': ('https://docs.micropython.org/en/latest', None),
+    'python': ('https://docs.python.org/3', None)
 }
 
 # -- Options for HTML output -------------------------------------------------
@@ -75,4 +77,17 @@
 
 # -- Options for autoapi -----------------------------------------------------
 autoapi_dirs = ['../../src']
-autoapi_root = 'api'
+autoapi_root = 'api'
+autoapi_file_patterns = ['*.pyi', '*.py']
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'private-members',
+    'show-inheritance',
+    'show-module-summary',
+    'imported-members',
+]
+autoapi_ignore = ["*_data_view_math*"]
+
+add_module_names = False
+python_maximum_signature_line_length = 60

docs/source/user_guide/tutorial.rst

@@ -325,8 +325,6 @@ like the following:
 ..  image:: hello_font.png
     :width: 160
 
-TODO: support alright fonts
-
 Markers and Scatterplots
 ------------------------
 
@@ -351,6 +349,20 @@ key-color for transparency.  The |ColoredBitmaps| shapes render 1-bit
 framebuffers in the specified colors.
 
 
+Convenience Methods
+===================
+
+So far we have been using a pattern of two-step creation of shapes, where
+we first create a shape and then add it to a layer of a surface.  Since you
+almost always want to add shapes to a layer immediatel after creating them,
+the |Surface| class has a collection of methods for creating and adding
+standard shapes in one step.
+
+TODO: example
+
+
+
+.. |FrameBuffer| replace:: :py:class:`~framebuf.FrameBuffer`
 .. |Surface| replace:: :py:class:`~tempe.surface.Surface`
 .. |refresh| replace:: :py:meth:`~tempe.surface.Surface.refresh`
 .. |Shape| replace:: :py:class:`~tempe.shapes.Shape`

src/tempe/_data_view_math.pyi

@@ -0,0 +1,3 @@
+"""Internal implementation for numeric operations on DataViews."""
+
+__all__ = []

src/tempe/bitmaps.pyi

@@ -0,0 +1,53 @@
+
+from array import array
+from collections.abc import Sequence, Iterable
+import framebuf
+from typing import Any
+
+from .shapes import ColoredGeometry, Shape, BLIT_KEY_RGB565, point, rectangle
+
+
+class Bitmaps(Shape):
+    """Draw framebuffer bitmaps at points"""
+
+    def __init__(
+        self,
+        geometry: Iterable[point],
+        buffers: Iterable[framebuf.FrameBuffer],
+        *,
+        key: int | None = None,
+        palette: Sequence[int] | None = None,
+        surface: "tempe.surface.Surface | None" = None,
+        clip: rectangle | None = None,
+    ): ...
+
+    def update(
+        self,
+        geometry: Iterable[point] | None = None,
+        buffers: Iterable[framebuf.FrameBuffer] | None = None,
+        **kwargs: Any,
+    ): ...
+
+    def __iter__(self) -> tuple[point, framebuf.FrameBuffer]: ...
+
+
+class ColoredBitmaps(ColoredGeometry[point]):
+    """Draw 1-bit framebuffers bitmaps at points in given colors."""
+
+    def __init__(
+        self,
+        geometry: Iterable[point],
+        colors: Iterable[int],
+        buffers: Iterable[framebuf.FrameBuffer],
+        *,
+        surface: "tempe.surface.Surface | None" = None,
+        clip: rectangle | None = None,
+    ): ...
+
+    def update(
+        self,
+        geometry: Iterable[point] | None = None,
+        colors: Iterable[int] | None = None,
+        buffers: Iterable[framebuf.FrameBuffer] | None = None,
+        **kwargs: Any,
+    ): ...

src/tempe/data_view.py

@@ -29,7 +29,7 @@ def __getitem__(self, index):
         return self.data[index]
 
     def __add__(self, other):
-        from .data_view_math import Add
+        from ._data_view_math import Add
 
         try:
             iter(other)
@@ -38,7 +38,7 @@ def __add__(self, other):
             return Add(self, Repeat(other))
 
     def __radd__(self, other):
-        from .data_view_math import Add
+        from ._data_view_math import Add
 
         try:
             iter(other)
@@ -47,7 +47,7 @@ def __radd__(self, other):
             return Add(Repeat(other), self)
 
     def __sub__(self, other):
-        from .data_view_math import Subtract
+        from ._data_view_math import Subtract
 
         try:
             iter(other)
@@ -56,7 +56,7 @@ def __sub__(self, other):
             return Subtract(self, Repeat(other))
 
     def __rsub__(self, other):
-        from .data_view_math import Subtract
+        from ._data_view_math import Subtract
 
         try:
             iter(other)
@@ -65,7 +65,7 @@ def __rsub__(self, other):
             return Subtract(Repeat(other), self)
 
     def __mul__(self, other):
-        from .data_view_math import Multiply
+        from ._data_view_math import Multiply
 
         try:
             iter(other)
@@ -74,7 +74,7 @@ def __mul__(self, other):
             return Multiply(self, Repeat(other))
 
     def __rmul__(self, other):
-        from .data_view_math import Multiply
+        from ._data_view_math import Multiply
 
         try:
             iter(other)
@@ -83,7 +83,7 @@ def __rmul__(self, other):
             return Multiply(Repeat(other), self)
 
     def __floordiv__(self, other):
-        from .data_view_math import FloorDivide
+        from ._data_view_math import FloorDivide
 
         try:
             iter(other)
@@ -92,7 +92,7 @@ def __floordiv__(self, other):
             return FloorDivide(self, Repeat(other))
 
     def __rfloordiv__(self, other):
-        from .data_view_math import FloorDivide
+        from ._data_view_math import FloorDivide
 
         try:
             iter(other)
@@ -101,7 +101,7 @@ def __rfloordiv__(self, other):
             return FloorDivide(Repeat(other), self)
 
     def __truediv__(self, other):
-        from .data_view_math import Divide
+        from ._data_view_math import Divide
 
         try:
             iter(other)
@@ -110,7 +110,7 @@ def __truediv__(self, other):
             return Divide(self, Repeat(other))
 
     def __rtruediv__(self, other):
-        from .data_view_math import Divide
+        from ._data_view_math import Divide
 
         try:
             iter(other)
@@ -119,22 +119,22 @@ def __rtruediv__(self, other):
             return Divide(Repeat(other), self)
 
     def __neg__(self):
-        from .data_view_math import Neg
+        from ._data_view_math import Neg
 
         return Neg(self)
 
     def __pos__(self):
-        from .data_view_math import Pos
+        from ._data_view_math import Pos
 
         return Pos(self)
 
     def __abs__(self):
-        from .data_view_math import Abs
+        from ._data_view_math import Abs
 
         return Abs(self)
 
     def __invert__(self):
-        from .data_view_math import Invert
+        from ._data_view_math import Invert
 
         return Invert(self)
 
@@ -259,8 +259,8 @@ class Count(DataView):
     """DataView that counts indefinitely from a start by a step."""
 
     def __init__(self, start=0, step=1):
-        self.start = 0
-        self.step = 1
+        self.start = start
+        self.step = step
 
     def __iter__(self):
         i = self.start
@@ -342,5 +342,5 @@ def __init__(self, data, n):
         self.n = n
 
     def __iter__(self):
-        for index in range(n):
-            yield self.data[index * (len(self.data) - 1) // (n - 1)]
+        for index in range(self.n):
+            yield self.data[index * (len(self.data) - 1) // (self.n - 1)]