Clarify render_cell JSON extra example

datasette/views/table_extras.py

@@ -395,11 +395,21 @@ class DisplayRowsExtra(Extra):
 class RenderCellExtra(Extra):
     description = "Rendered HTML for each cell using the render_cell plugin hook"
     example = ExtraExample(
-        value=[
-            {},
-            {"content": "<strong>Custom rendered HTML</strong>"},
-        ],
-        note="Only columns whose rendered value differs from the default are included.",
+        value={
+            "rows": [
+                {"id": 1, "content": "hello"},
+                {"id": 4, "content": "RENDER_CELL_DEMO"},
+            ],
+            "render_cell": [
+                {},
+                {"content": "<strong>Custom rendered HTML</strong>"},
+            ],
+        },
+        note=(
+            "The ``render_cell`` array has one item per row, in the same order as "
+            "the ``rows`` array. Each object is keyed by column name. Only columns "
+            "whose rendered value differs from the default are included."
+        ),
     )
     scopes = frozenset({ExtraScope.TABLE})
 

docs/json_api.rst

@@ -428,16 +428,28 @@ The available table extras are listed below.
 ``render_cell``
     Rendered HTML for each cell using the render_cell plugin hook
 
-    Only columns whose rendered value differs from the default are included.
+    The ``render_cell`` array has one item per row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
 
     .. code-block:: json
 
-        [
-          {},
-          {
-            "content": "<strong>Custom rendered HTML</strong>"
-          }
-        ]
+        {
+          "rows": [
+            {
+              "id": 1,
+              "content": "hello"
+            },
+            {
+              "id": 4,
+              "content": "RENDER_CELL_DEMO"
+            }
+          ],
+          "render_cell": [
+            {},
+            {
+              "content": "<strong>Custom rendered HTML</strong>"
+            }
+          ]
+        }
 
 ``debug``
     Extra debug information

tests/test_docs.py

@@ -122,6 +122,14 @@ def test_table_extra_examples_are_documented():
     assert ".. code-block:: json" in section
 
 
+def test_render_cell_extra_example_explains_row_and_column_mapping():
+    content = (docs_path / "json_api.rst").read_text()
+    section = content.split("``render_cell``")[-1].split("``query``")[0]
+    assert "same order as the ``rows`` array" in section
+    assert '"rows": [' in section
+    assert '"render_cell": [' in section
+
+
 @pytest.fixture(scope="session")
 def documented_labels():
     labels = set()