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 6822378 for how it works.

Here's the class that documented:

datasette/datasette/context.py

Lines 54 to 68 in 6822378

    
           @dataclass 
        
           class Table: 
        
               "A table is a useful thing" 
        
               name: str = doc("The name of the table") 
        
               columns: List[str] = doc("List of column names in the table") 
        
               primary_keys: List[str] = doc("List of column names that are primary keys") 
        
               count: int = doc("Number of rows in the table") 
        
               hidden: bool = doc( 
        
                   "Should this table default to being hidden in the main database UI?" 
        
               ) 
        
               fts_table: Optional[str] = doc( 
        
                   "If this table has FTS support, the accompanying FTS table name" 
        
               ) 
        
               foreign_keys: ForeignKey = doc("List of foreign keys for this table") 
        
               private: bool = doc("Private tables are not visible to signed-out anonymous users")

And the code that generates the rST:

datasette/datasette/context.py

Lines 19 to 45 in 6822378

    
           def rst_docs_for_dataclass(klass: Any) -> str: 
        
               """Generate reStructuredText (reST) docs for a dataclass.""" 
        
               docs = [] 
        
               # Class name and docstring 
        
               docs.append(klass.__name__) 
        
               docs.append("-" * len(klass.__name__)) 
        
               docs.append("") 
        
               if klass.__doc__: 
        
                   docs.append(klass.__doc__) 
        
                   docs.append("") 
        
               # Dataclass fields 
        
               docs.append("Fields") 
        
               docs.append("~~~~~~") 
        
               docs.append("") 
        
               for name, field_info in klass.__dataclass_fields__.items(): 
        
                   if is_builtin_type(field_info.type): 
        
                       # <class 'int'> 
        
                       type_name = field_info.type.__name__ 
        
                   else: 
        
                       # List[str] 
        
                       type_name = str(field_info.type).replace("typing.", "") 
        
                   docs.append(f':{name} - ``{type_name}``: {field_info.metadata.get("doc", "")}') 
        
               return "\n".join(docs)

And the bit that cog executes:

datasette/docs/template_context.rst

Lines 9 to 12 in 6822378

    
           .. [[[cog 
        
               from datasette.context import rst_docs_for_dataclass, Table 
        
               cog.out(rst_docs_for_dataclass(Table)) 
        
           .. ]]]

	@dataclass
	class Table:
	"A table is a useful thing"
	name: str = doc("The name of the table")
	columns: List[str] = doc("List of column names in the table")
	primary_keys: List[str] = doc("List of column names that are primary keys")
	count: int = doc("Number of rows in the table")
	hidden: bool = doc(
	"Should this table default to being hidden in the main database UI?"
	)
	fts_table: Optional[str] = doc(
	"If this table has FTS support, the accompanying FTS table name"
	)
	foreign_keys: ForeignKey = doc("List of foreign keys for this table")
	private: bool = doc("Private tables are not visible to signed-out anonymous users")

	def rst_docs_for_dataclass(klass: Any) -> str:
	"""Generate reStructuredText (reST) docs for a dataclass."""
	docs = []

	# Class name and docstring
	docs.append(klass.__name__)
	docs.append("-" * len(klass.__name__))
	docs.append("")
	if klass.__doc__:
	docs.append(klass.__doc__)
	docs.append("")

	# Dataclass fields
	docs.append("Fields")
	docs.append("~~~~~~")
	docs.append("")

	for name, field_info in klass.__dataclass_fields__.items():
	if is_builtin_type(field_info.type):
	# <class 'int'>
	type_name = field_info.type.__name__
	else:
	# List[str]
	type_name = str(field_info.type).replace("typing.", "")
	docs.append(f':{name} - ``{type_name}``: {field_info.metadata.get("doc", "")}')

	return "\n".join(docs)

	.. [[[cog
	from datasette.context import rst_docs_for_dataclass, Table
	cog.out(rst_docs_for_dataclass(Table))
	.. ]]]

Uh oh!

Datasette 1.0 documented template context (maybe via API docs) #1510

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions