Datasette 1.0 documented template context (maybe via API docs)

[simonw]

Documented context plus protective unit tests. Goal is that custom templates built for 1.x will not break without a 2.x release.

[simonw]

If I set a rule that everything available in the template context MUST also be available via the JSON API (maybe through an extras mechanism) I can combine this with API documentation and solve both at once.

[simonw]

I really like the idea of making this effectively the same thing as the fully documented, stable JSON API that comes as part of 1.0. If you want to know what will be available to your templates, consult the API documentation.

[simonw]

I prototyped an approach to this using dataclasses and a cog mechanism for turning those into rendered tables in Sphinx. Here's what that prototype looks like:

See https://github.com/simonw/datasette/commit/68223784167fdec4e7ebfca56002a6548ba7b423 for how it works.

Here's the class that documented:

https://github.com/simonw/datasette/blob/68223784167fdec4e7ebfca56002a6548ba7b423/datasette/context.py#L54-L68

And the code that generates the rST: https://github.com/simonw/datasette/blob/68223784167fdec4e7ebfca56002a6548ba7b423/datasette/context.py#L19-L45

And the bit that cog executes: https://github.com/simonw/datasette/blob/68223784167fdec4e7ebfca56002a6548ba7b423/docs/template_context.rst?plain=1#L9-L12