From d9b508ffaa91f9f1840b366f5d282712d445f16b Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sun, 6 Feb 2022 22:30:00 -0800
Subject: [PATCH] @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
---
 datasette/utils/__init__.py | 16 ++++++++++++++--
 docs/conf.py                |  2 +-
 docs/internals.rst          | 11 +++++++++++
 tests/test_docs.py          | 18 +++++++++++++++++-
 4 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/datasette/utils/__init__.py b/datasette/utils/__init__.py
index dc4e1c99..610e916f 100644
--- a/datasette/utils/__init__.py
+++ b/datasette/utils/__init__.py
@@ -12,6 +12,7 @@ import os
 import re
 import shlex
 import tempfile
+import typing
 import time
 import types
 import shutil
@@ -59,8 +60,17 @@ Column = namedtuple(
     "Column", ("cid", "name", "type", "notnull", "default_value", "is_pk", "hidden")
 )
 
+functions_marked_as_documented = []
 
-async def await_me_maybe(value):
+
+def documented(fn):
+    functions_marked_as_documented.append(fn)
+    return fn
+
+
+@documented
+async def await_me_maybe(value: typing.Any) -> typing.Any:
+    "If value is callable, call it. If awaitable, await it. Otherwise return it."
     if callable(value):
         value = value()
     if asyncio.iscoroutine(value):
@@ -915,7 +925,9 @@ class BadMetadataError(Exception):
     pass
 
 
-def parse_metadata(content):
+@documented
+def parse_metadata(content: str) -> dict:
+    "Detects if content is JSON or YAML and parses it appropriately."
     # content can be JSON or YAML
     try:
         return json.loads(content)
diff --git a/docs/conf.py b/docs/conf.py
index 89009ea9..d114bc52 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,7 +31,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.extlinks"]
+extensions = ["sphinx.ext.extlinks", "sphinx.ext.autodoc"]
 
 extlinks = {
     "issue": ("https://github.com/simonw/datasette/issues/%s", "#"),
diff --git a/docs/internals.rst b/docs/internals.rst
index 632f7d7a..12ef5c54 100644
--- a/docs/internals.rst
+++ b/docs/internals.rst
@@ -865,6 +865,17 @@ This function accepts a string containing either JSON or YAML, expected to be of
 
 If the metadata cannot be parsed as either JSON or YAML the function will raise a ``utils.BadMetadataError`` exception.
 
+.. autofunction:: datasette.utils.parse_metadata
+
+.. _internals_utils_await_me_maybe:
+
+await_me_maybe(value)
+---------------------
+
+Utility function for calling ``await`` on a return value if it is awaitable, otherwise returning the value. This is used by Datasette to support plugin hooks that can optionally return awaitable functions. Read more about this function in `The “await me maybe” pattern for Python asyncio <https://simonwillison.net/2020/Sep/2/await-me-maybe/>`__.
+
+.. autofunction:: datasette.utils.await_me_maybe
+
 .. _internals_tracer:
 
 datasette.tracer
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 0d17b8e3..cd5a6c13 100644
--- a/tests/test_docs.py
+++ b/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