Add backend overview to docs (#43)

docs/backends.rst

@@ -1,6 +1,70 @@
 Backends
 ========
 
+Overview
+--------
+
+The table below gives an overview of the names in the different ``rendercanvas`` backend modules.
+
+.. list-table::
+
+    *   - **backend module**
+        - **names**
+        - **purpose**
+    *   - ``auto``
+        - | ``RenderCanvas``
+          | ``loop``
+        - | Select a backend automatically.
+    *   - ``glfw``
+        - | ``GlfwRenderCanvas``
+          | ``RenderCanvas`` (alias)
+          | ``loop`` (an ``AsyncioLoop``)
+        - | A lightweight backend.
+    *   - ``jupyter``
+        - | ``JupyterRenderCanvas``
+          | ``RenderCanvas`` (alias)
+          | ``loop`` (an ``AsyncioLoop``)
+        - | Integrate in Jupyter notebook / lab.
+    *   - ``offscreen``
+        - | ``OffscreenRenderCanvas``
+          | ``RenderCanvas`` (alias)
+          | ``loop`` (a ``StubLoop``)
+        - | For offscreen rendering.
+    *   - ``qt``
+        - | ``QRenderCanvas`` (toplevel)
+          | ``RenderCanvas`` (alias)
+          | ``QRenderWidget`` (subwidget)
+          | ``QtLoop``
+          | ``loop``
+        - | Create a standalone canvas using Qt, or
+          | integrate a render canvas in a Qt application.
+    *   - ``wx``
+        - | ``WxRenderCanvas`` (toplevel)
+          | ``RenderCanvas`` (alias)
+          | ``WxRenderWidget`` (subwidget)
+          | ``WxLoop``
+          | ``loop``
+        - | Create a standalone canvas using wx, or
+          | integrate a render canvas in a wx application.
+
+
+There are also two loop-backends. These are mainly intended for use with the glfw backend:
+
+.. list-table::
+
+    *   - **backend module**
+        - **names**
+        - **purpose**
+    *   - ``asyncio``
+        - | ``AsyncoLoop``
+          | ``loop``
+        - | Provide a generic loop based on Asyncio.
+    *   - ``trio``
+        - | ``TrioLoop``
+          | ``loop``
+        - | Provide a loop based on Trio.
+
+
 The auto backend
 -----------------
 

rendercanvas/glfw.py

@@ -7,7 +7,7 @@
 or ``sudo apt install libglfw3-wayland`` when using Wayland.
 """
 
-__all__ = ["RenderCanvas", "loop"]
+__all__ = ["GlfwRenderCanvas", "RenderCanvas", "loop"]
 
 import sys
 import time

rendercanvas/jupyter.py

@@ -3,7 +3,7 @@
 can be used as cell output, or embedded in an ipywidgets gui.
 """
 
-__all__ = ["RenderCanvas", "loop"]
+__all__ = ["JupyterRenderCanvas", "RenderCanvas", "loop"]
 
 import time
 

rendercanvas/offscreen.py

@@ -2,7 +2,7 @@
 Offscreen canvas. No scheduling.
 """
 
-__all__ = ["RenderCanvas", "loop"]
+__all__ = ["OffscreenRenderCanvas", "RenderCanvas", "loop"]
 
 import time
 
@@ -13,7 +13,7 @@ class OffscreenCanvasGroup(BaseCanvasGroup):
     pass
 
 
-class ManualOffscreenRenderCanvas(BaseRenderCanvas):
+class OffscreenRenderCanvas(BaseRenderCanvas):
     """An offscreen canvas intended for manual use.
 
     Call the ``.draw()`` method to perform a draw and get the result.
@@ -90,7 +90,7 @@ def draw(self):
         return self._last_image
 
 
-RenderCanvas = ManualOffscreenRenderCanvas
+RenderCanvas = OffscreenRenderCanvas
 
 
 class StubLoop(BaseLoop):

rendercanvas/qt.py

@@ -3,7 +3,7 @@
 can be used as a standalone window or in a larger GUI.
 """
 
-__all__ = ["QRenderWidget", "RenderCanvas", "RenderWidget", "loop"]
+__all__ = ["QRenderCanvas", "QRenderWidget", "QtLoop", "RenderCanvas", "loop"]
 
 import sys
 import ctypes

rendercanvas/stub.py

@@ -2,7 +2,7 @@
 A stub backend for documentation purposes.
 """
 
-__all__ = ["RenderCanvas", "loop"]
+__all__ = ["RenderCanvas", "StubLoop", "StubRenderCanvas", "loop"]
 
 from .base import BaseCanvasGroup, WrapperRenderCanvas, BaseRenderCanvas, BaseLoop
 

rendercanvas/wx.py

@@ -3,7 +3,7 @@
 can be used as a standalone window or in a larger GUI.
 """
 
-__all__ = ["RenderCanvas", "RenderWidget", "WxRenderWidget", "loop"]
+__all__ = ["RenderCanvas", "WxLoop", "WxRenderCanvas", "WxRenderWidget", "loop"]
 
 import sys
 import time

tests/test_backends.py

@@ -251,7 +251,7 @@ def test_offscreen_module():
 
     canvas_class = m.get_canvas_class()
     m.check_canvas(canvas_class)
-    assert canvas_class.name == "ManualOffscreenRenderCanvas"
+    assert canvas_class.name == "OffscreenRenderCanvas"
 
 
 def test_qt_module():

tests/test_context.py

@@ -1,7 +1,7 @@
 import numpy as np
 from rendercanvas.utils.bitmappresentadapter import BitmapPresentAdapter
 from rendercanvas.utils.bitmaprenderingcontext import BitmapRenderingContext
-from rendercanvas.offscreen import ManualOffscreenRenderCanvas
+from rendercanvas.offscreen import OffscreenRenderCanvas as ManualOffscreenRenderCanvas
 
 from testutils import can_use_wgpu_lib, run_tests
 import pytest

tests/test_offscreen.py

@@ -11,7 +11,7 @@
 
 
 def test_offscreen_selection_using_env_var():
-    from rendercanvas.offscreen import ManualOffscreenRenderCanvas
+    from rendercanvas.offscreen import OffscreenRenderCanvas
 
     ori = os.getenv("RENDERCANVAS_FORCE_OFFSCREEN")
     os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = "1"
@@ -24,20 +24,20 @@ def test_offscreen_selection_using_env_var():
             for value in ["", "0", "false", "False", "wut"]:
                 os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = value
                 module = select_backend()
-                assert module.RenderCanvas is not ManualOffscreenRenderCanvas
+                assert module.RenderCanvas is not OffscreenRenderCanvas
 
         for value in ["1", "true", "True"]:
             os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = value
             module = select_backend()
-            assert module.RenderCanvas is ManualOffscreenRenderCanvas
+            assert module.RenderCanvas is OffscreenRenderCanvas
 
     finally:
         if ori is not None:
             os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = ori
 
 
 def test_offscreen_selection_using_legacyt_env_var():
-    from rendercanvas.offscreen import ManualOffscreenRenderCanvas
+    from rendercanvas.offscreen import OffscreenRenderCanvas
 
     ori1 = os.getenv("RENDERCANVAS_FORCE_OFFSCREEN")
     ori2 = os.getenv("WGPU_FORCE_OFFSCREEN")
@@ -53,12 +53,12 @@ def test_offscreen_selection_using_legacyt_env_var():
             for value in ["", "0", "false", "False", "wut"]:
                 os.environ["WGPU_FORCE_OFFSCREEN"] = value
                 module = select_backend()
-                assert module.RenderCanvas is not ManualOffscreenRenderCanvas
+                assert module.RenderCanvas is not OffscreenRenderCanvas
 
         for value in ["1", "true", "True"]:
             os.environ["WGPU_FORCE_OFFSCREEN"] = value
             module = select_backend()
-            assert module.RenderCanvas is ManualOffscreenRenderCanvas
+            assert module.RenderCanvas is OffscreenRenderCanvas
 
     finally:
         if ori1 is not None: