Documentation for filters, plus new documentation unit test

https://simonwillison.net/2018/Jul/28/documentation-unit-tests/

Author: simonw

docs/json_api.rst

@@ -176,10 +176,68 @@ querystring arguments:
 
 .. _table_arguments:
 
-Special table arguments
------------------------
+Table arguments
+---------------
+
+The Datasette table view takes a number of special querystring arguments.
+
+Column filter arguments
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can filter the data returned by the table based on column values using a querystring argument.
+
+``?column__exact=value`` or ``?_column=value``
+    Returns rows where the specified column exactly matches the value.
+
+``?column__not=value``
+    Returns rows where the column does not match the value.
+
+``?column__contains=value``
+    Rows where the string column contains the specified value (``column like "%value%"`` in SQL).
+
+``?column__endswith=value``
+    Rows where the string column ends with the specified value (``column like "%value"`` in SQL).
+
+``?column__startswith=value``
+    Rows where the string column starts with the specified value (``column like "value%"`` in SQL).
+
+``?column__gt=value``
+    Rows which are greater than the specified value.
+
+``?column__gte=value``
+    Rows which are greater than or equal to the specified value.
 
-The Datasette table view takes a number of special querystring arguments:
+``?column__lt=value``
+    Rows which are less than the specified value.
+
+``?column__lte=value``
+    Rows which are less than or equal to the specified value.
+
+``?column__like=value``
+    Match rows with a LIKE clause, case insensitive and with ``%`` as the wildcard character.
+
+``?column__glob=value``
+    Similar to LIKE but uses Unix wildcard syntax and is case sensitive.
+
+``?column__arraycontains=value``
+    Works against columns that contain JSON arrays - matches if any of the values in that array match.
+
+    This is only available if the ``json1`` SQLite extension is enabled.
+
+``?column__isnull=1``
+    Matches rows where the column is null.
+
+``?column__notnull=1``
+    Matches rows where the column is not null.
+
+``?column__isblank=1``
+    Matches rows where the column is blank, meaning null or the empty string.
+
+``?column__notblank=1``
+    Matches rows where the column is not blank.
+
+Special table arguments
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ``?_labels=on/off``
     Expand foreign key references for every possible column. See below.

tests/test_docs.py

@@ -4,6 +4,7 @@
 from click.testing import CliRunner
 from datasette import app
 from datasette.cli import cli
+from datasette.filters import Filters
 from pathlib import Path
 import pytest
 import re
@@ -71,3 +72,20 @@ def documented_views():
 @pytest.mark.parametrize("view_class", [v for v in dir(app) if v.endswith("View")])
 def test_view_classes_are_documented(documented_views, view_class):
     assert view_class in documented_views
+
+
+@pytest.fixture(scope="session")
+def documented_table_filters():
+    json_api_rst = (docs_path / "json_api.rst").read_text()
+    section = json_api_rst.split(".. _table_arguments:")[-1]
+    # Lines starting with ``?column__exact= are docs for filters
+    return set(
+        line.split("__")[1].split("=")[0]
+        for line in section.split("\n")
+        if line.startswith("``?column__")
+    )
+
+
+@pytest.mark.parametrize("filter", [f.key for f in Filters._filters])
+def test_table_filters_are_documented(documented_table_filters, filter):
+    assert filter in documented_table_filters