Prototype of rst_docs_for_dataclass mechanism, refs #1510

docs/conf.py

@@ -31,7 +31,12 @@
 # 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", "sphinx.ext.autodoc", "sphinx_copybutton"]
+extensions = [
+    "sphinx.ext.extlinks",
+    "sphinx.ext.autodoc",
+    "sphinx_copybutton",
+    "jsoncontext",
+]
 
 extlinks = {
     "issue": ("https://github.com/simonw/datasette/issues/%s", "#%s"),

docs/index.rst

@@ -57,6 +57,7 @@ Contents
    settings
    introspection
    custom_templates
+   template_context
    plugins
    writing_plugins
    plugin_hooks

docs/jsoncontext.py

@@ -0,0 +1,28 @@
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+from importlib import import_module
+import json
+
+
+class JSONContextDirective(SphinxDirective):
+    required_arguments = 1
+
+    def run(self):
+        module_path, class_name = self.arguments[0].rsplit(".", 1)
+        try:
+            module = import_module(module_path)
+            dataclass = getattr(module, class_name)
+        except ImportError:
+            warning = f"Unable to import {self.arguments[0]}"
+            return [nodes.error(None, nodes.paragraph(text=warning))]
+
+        doc = json.dumps(
+            dataclass.__annotations__, indent=4, sort_keys=True, default=repr
+        )
+        doc_node = nodes.literal_block(text=doc)
+
+        return [doc_node]
+
+
+def setup(app):
+    app.add_directive("jsoncontext", JSONContextDirective)

docs/template_context.rst

@@ -0,0 +1,29 @@
+.. _template_context:
+
+Template context
+================
+
+This page describes the variables made available to templates used by Datasette to render different pages of the application.
+
+
+.. [[[cog
+    from datasette.context import rst_docs_for_dataclass, Table
+    cog.out(rst_docs_for_dataclass(Table))
+.. ]]]
+Table
+-----
+
+A table is a useful thing
+
+Fields
+~~~~~~
+
+:name - ``str``: The name of the table
+:columns - ``List[str]``: List of column names in the table
+:primary_keys - ``List[str]``: List of column names that are primary keys
+:count - ``int``: Number of rows in the table
+:hidden - ``bool``: Should this table default to being hidden in the main database UI?
+:fts_table - ``Optional[str]``: If this table has FTS support, the accompanying FTS table name
+:foreign_keys - ``ForeignKey``: List of foreign keys for this table
+:private - ``bool``: Private tables are not visible to signed-out anonymous users
+.. [[[end]]]