Add debug and request JSON extra examples

datasette/views/table_extras.py

@@ -308,6 +308,7 @@ class IsViewExtra(Extra):
 
 class DebugExtra(Extra):
     description = "Extra debug information"
+    example = ExtraExample("/fixtures/facetable.json?_extra=debug")
     scopes = frozenset({ExtraScope.TABLE})
 
     async def resolve(self, context):
@@ -321,6 +322,7 @@ class DebugExtra(Extra):
 
 class RequestExtra(Extra):
     description = "Full information about the request"
+    example = ExtraExample("/fixtures/facetable.json?_extra=request")
     scopes = frozenset({ExtraScope.TABLE})
 
     async def resolve(self, context):

docs/json_api.rst

@@ -454,9 +454,40 @@ The available table extras are listed below.
 ``debug``
     Extra debug information
 
+    ``GET /fixtures/facetable.json?_extra=debug``
+
+    .. code-block:: json
+
+        {
+          "resolved": "ResolvedTable(db=<Database: fixtures (mutable, size=249856)>, table='facetable', is_view=False)",
+          "url_vars": {
+            "database": "fixtures",
+            "table": "facetable",
+            "format": "json"
+          },
+          "nofacet": null,
+          "nosuggest": null
+        }
+
 ``request``
     Full information about the request
 
+    ``GET /fixtures/facetable.json?_extra=request``
+
+    .. code-block:: json
+
+        {
+          "url": "http://localhost/fixtures/facetable.json?_extra=request",
+          "path": "/fixtures/facetable.json",
+          "full_path": "/fixtures/facetable.json?_extra=request",
+          "host": "localhost",
+          "args": {
+            "_extra": [
+              "request"
+            ]
+          }
+        }
+
 ``query``
     Details of the underlying SQL query
 

tests/test_docs.py

@@ -130,6 +130,19 @@ def test_render_cell_extra_example_explains_row_and_column_mapping():
     assert '"render_cell": [' in section
 
 
+def test_debug_and_request_extra_examples_are_documented():
+    content = (docs_path / "json_api.rst").read_text()
+    section = content.split(".. _json_api_extra:")[-1].split(".. _table_arguments:")[0]
+
+    debug_section = section.split("``debug``")[-1].split("``request``")[0]
+    assert "GET /fixtures/facetable.json?_extra=debug" in debug_section
+    assert '"url_vars": {' in debug_section
+
+    request_section = section.split("``request``")[-1].split("``query``")[0]
+    assert "GET /fixtures/facetable.json?_extra=request" in request_section
+    assert '"full_path":' in request_section
+
+
 @pytest.fixture(scope="session")
 def documented_labels():
     labels = set()