This improves the doc situation

There are still some problems & some build warnings but at least the
sphinx docs have useful content now.

docs/adafruit_blinka_raspberry_pi5_piomatter.rst

@@ -1 +1,8 @@
-.. automodule:: adafruit_blinka_raspberry_pi5_piomatter
+HUB75 matrix driver for Raspberry Pi 5 using PIO
+------------------------------------------------
+
+.. autosummary::
+   :toctree: _generate
+   :recursive:
+
+    adafruit_blinka_raspberry_pi5_piomatter

docs/conf.py

@@ -26,13 +26,27 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    "autoapi.extension",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
 ]
 
-autosummary_generate = True
+autoapi_keep_files = True
+autoapi_dirs = ["../src/adafruit_blinka_raspberry_pi5_piomatter"]
+autoapi_add_toctree_entry = True
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "special-members",
+    "show-module-summary",
+]
+
+autoapi_python_class_content = "both"
+autoapi_python_use_implicit_namespaces = True
+autoapi_template_dir = "autoapi/templates"
+autoapi_root = "api"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/requirements.txt

@@ -3,5 +3,6 @@
 # SPDX-License-Identifier: Unlicense
 
 sphinx
+sphinx-autoapi
 sphinx-rtd-theme
 sphinxcontrib-jquery

src/adafruit_blinka_raspberry_pi5_piomatter/__init__.py

@@ -1,3 +1,21 @@
+"""
+HUB75 matrix driver for Raspberry Pi 5 using PIO
+------------------------------------------------
+
+.. currentmodule:: adafruit_blinka_raspberry_pi5_piomatter
+
+.. autosummary::
+    :toctree: _generate
+    :recursive:
+    :class: Orientation Pinout Colorspace Geometry PioMatter
+
+    Orientation
+    Pinout
+    Colorspace
+    Geometry
+    PioMatter
+"""
+
 from ._piomatter import (
     Colorspace,
     Geometry,

src/adafruit_blinka_raspberry_pi5_piomatter/pixelmappers.py

@@ -1,3 +1,5 @@
+"""Functions to define the layout of complex setups, particularly multi-connector matrices"""
+
 def simple_multilane_mapper(width, height, n_addr_lines, n_lanes):
     """A simple mapper for 4+ pixel lanes
 
@@ -7,7 +9,7 @@ def simple_multilane_mapper(width, height, n_addr_lines, n_lanes):
     Rotation is not supported, and neither are more complicated arrangements of panels
     within a single chain (no support for serpentine or stacked panels within a segment)
 
-    .. code-block:: raw
+    .. code-block::
 
         0 -> [panel] -> [panel]
         1 -> [panel] -> [panel]

src/pymain.cpp

@@ -119,16 +119,7 @@ PYBIND11_MODULE(_piomatter, m) {
         HUB75 matrix driver for Raspberry Pi 5 using PIO
         ------------------------------------------------
 
-        .. currentmodule:: adafruit_blinka_raspberry_pi5_piomatter
+        .. currentmodule:: adafruit_blinka_raspberry_pi5_piomatter._piomatter
-
-        .. autosummary::
-           :toctree: _generate
-
-           Orientation
-           Pinout
-           Colorspace
-           Geometry
-           PioMatter
     )pbdoc";
 
     py::enum_<piomatter::orientation>(
@@ -265,16 +256,16 @@ If 2 or 3 connectors are used, then there are 4 or 6 lanes.
 HUB75 matrix driver for Raspberry Pi 5 using PIO
 
 ``colorspace`` controls the colorspace that will be used for data to be displayed.
-It must be one of the ``Colorspace`` constants. Which to use depends on what data
+It must be one of the `Colorspace` constants. Which to use depends on what data
 your displaying and how it is processed before copying into the framebuffer.
 
 ``pinout`` defines which pins the panels are wired to. Different pinouts can
 support different hardware breakouts and panels with different color order. The
-value must be one of the ``Pinout`` constants.
+value must be one of the `Pinout` constants.
 
 ``framebuffer`` a numpy array that holds pixel data in the appropriate colorspace.
 
-``geometry`` controls the size and shape of the panel. The value must be a ``Geometry``
+``geometry`` controls the size and shape of the panel. The value must be a `Geometry`
 instance.
 )pbdoc")
         .def(py::init(&make_piomatter), py::arg("colorspace"),