@documented decorator plus unit test plus sphinx.ext.autodoc

New mechanism for marking datasette.utils functions that should be covered by the
documentation, then testing that they have indeed been documented.

Also enabled sphinx.ext.autodoc which can now be used to embed the documented
versions of those functions.

Refs #1176

tests/test_docs.py

@@ -2,7 +2,7 @@
 Tests to ensure certain things are documented.
 """
 from click.testing import CliRunner
-from datasette import app
+from datasette import app, utils
 from datasette.cli import cli
 from datasette.filters import Filters
 from pathlib import Path
@@ -86,3 +86,19 @@ def documented_table_filters():
 @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
+
+
+@pytest.fixture(scope="session")
+def documented_fns():
+    internals_rst = (docs_path / "internals.rst").read_text()
+    # Any line that starts .. _internals_utils_X
+    lines = internals_rst.split("\n")
+    prefix = ".. _internals_utils_"
+    return {
+        line.split(prefix)[1].split(":")[0] for line in lines if line.startswith(prefix)
+    }
+
+
+@pytest.mark.parametrize("fn", utils.functions_marked_as_documented)
+def test_functions_marked_with_documented_are_documented(documented_fns, fn):
+    assert fn.__name__ in documented_fns