Update mkdocs configuration

docs/api_reference.md

@@ -2,7 +2,12 @@
 
 This page documents the PDL members that likely to be used to run PDL programs from Python.
 
+## Program
+::: pdl.pdl_ast
+
 ## Interpreter
+::: pdl.pdl_interpreter
+<!-- 
 ::: pdl.pdl_interpreter.InterpreterState
     options:
         show_if_no_docstring: true
@@ -13,9 +18,4 @@ This page documents the PDL members that likely to be used to run PDL programs f
 
 ::: pdl.pdl_interpreter.process_prog
     options:
-        show_if_no_docstring: true
-
-## Program
-::: pdl.pdl_ast.Program
-    options:
-        show_if_no_docstring: true
+        show_if_no_docstring: true -->

mkdocs.yml

@@ -63,14 +63,17 @@ plugins:
           show_bases: true
           show_symbol_type_toc: true
           show_submodules: false
-          show_root_toc_entry: false
+          show_root_toc_entry: true
           docstring_section_style: table
           inherited_members: false
           summary: true
-          docstring_style: null
+          docstring_style: google
           show_if_no_docstring: false
-          show_labels: false
+          show_labels: true
           heading_level: 3
+          show_symbol_type_heading: true
+          show_signature: true
+          show_signature_annotations: true
 
 
 markdown_extensions:

pdl/pdl_ast.py

@@ -82,23 +82,43 @@ class RegexParser(Parser):
 
 
 class Block(BaseModel):
-    """PDL program block"""
+    """PDL block: common fields of all PDL blocks."""
 
     model_config = ConfigDict(extra="forbid")
+
     description: Optional[str] = None
+    """Documentation associated to the block.
+    """
     spec: Any = None
+    """Type specification of the result of the block.
+    """
     defs: dict[str, "BlocksType"] = {}
+    """Set of definitions executed before the execution of the block.
+    """
     assign: Optional[str] = Field(default=None, alias="def")
+    """Name of the variable used to store the result of the execution of the block.
+    """
     show_result: bool = True
-    result: Optional[Any] = None
+    """Ignore the value computed by the block.
+    """
     parser: Optional[ParserType] = None
-    location: Optional[LocationType] = None
-    has_error: bool = False
+    """Parser to use to construct a value out of a string result."""
     fallback: Optional["BlocksType"] = None
+    """Block to execute in case of error.
+    """
     role: RoleType = None
+    """Role associated to the block and sub-blocks.
+    """
+
+    # Fields for internal use
+    result: Optional[Any] = None
+    location: Optional[LocationType] = None
+    has_error: bool = False
 
 
 class FunctionBlock(Block):
+    """Function declaration"""
+
     model_config = ConfigDict(extra="forbid")
     kind: Literal[BlockKind.FUNCTION] = BlockKind.FUNCTION
     function: Optional[dict[str, Any]]