From 97dce3ad06a4f5cc408c58a6b056485b3ff20d6c Mon Sep 17 00:00:00 2001
From: Dimitri Yatsenko <dimitri.yatsenko@gmail.com>
Date: Wed, 20 May 2026 18:14:19 -0500
Subject: [PATCH] docs: fix code formatting on rendered codecs API page

Three issues caused docstring code to render as plain text on
https://docs.datajoint.com/api/datajoint/codecs/ (mkdocstrings is
configured for docstring_style: numpy + Markdown-flavored bodies):

- Codec class docstring used reST '::' literal blocks for the two
  table-definition examples. Replaced with Markdown fenced code blocks.
- decode_attribute used Google-style 'Args:'/'Returns:' sections in a
  NumPy-configured doc generator. Converted to NumPy 'Parameters'/
  'Returns' with dashed underlines so it renders as a parameter table
  consistent with the rest of the module.
- Module-level 'Example:' block now uses a Markdown fenced code block
  rather than relying on 4-space indentation.

No behavior change - docstrings only.
---
 src/datajoint/codecs.py | 97 ++++++++++++++++++++++++-----------------
 1 file changed, 56 insertions(+), 41 deletions(-)

diff --git a/src/datajoint/codecs.py b/src/datajoint/codecs.py
index d7fbaf42d..2719e9509 100644
--- a/src/datajoint/codecs.py
+++ b/src/datajoint/codecs.py
@@ -8,29 +8,32 @@
 Codecs auto-register when subclassed - no decorator needed (Python 3.10+).
 
 Example:
-    class GraphCodec(dj.Codec):
-        name = "graph"
 
-        def get_dtype(self, is_store: bool) -> str:
-            return "<blob>"
+```python
+class GraphCodec(dj.Codec):
+    name = "graph"
 
-        def encode(self, graph, *, key=None, store_name=None):
-            return {'nodes': list(graph.nodes()), 'edges': list(graph.edges())}
-
-        def decode(self, stored, *, key=None):
-            import networkx as nx
-            G = nx.Graph()
-            G.add_nodes_from(stored['nodes'])
-            G.add_edges_from(stored['edges'])
-            return G
-
-    # Then use in table definitions:
-    class MyTable(dj.Manual):
-        definition = '''
-        id : uint16
-        ---
-        data : <graph>
-        '''
+    def get_dtype(self, is_store: bool) -> str:
+        return "<blob>"
+
+    def encode(self, graph, *, key=None, store_name=None):
+        return {'nodes': list(graph.nodes()), 'edges': list(graph.edges())}
+
+    def decode(self, stored, *, key=None):
+        import networkx as nx
+        G = nx.Graph()
+        G.add_nodes_from(stored['nodes'])
+        G.add_edges_from(stored['edges'])
+        return G
+
+# Then use in table definitions:
+class MyTable(dj.Manual):
+    definition = '''
+    id : uint16
+    ---
+    data : <graph>
+    '''
+```
 """
 
 from __future__ import annotations
@@ -85,20 +88,24 @@ class Codec(ABC):
     ...         G.add_edges_from(stored['edges'])
     ...         return G
 
-    Use in table definitions::
+    Use in table definitions:
 
-        class Connectivity(dj.Manual):
-            definition = '''
-            id : uint16
-            ---
-            graph_data : <graph>
-            '''
+    ```python
+    class Connectivity(dj.Manual):
+        definition = '''
+        id : uint16
+        ---
+        graph_data : <graph>
+        '''
+    ```
 
-    Skip auto-registration for abstract base classes::
+    Skip auto-registration for abstract base classes:
 
-        class ExternalOnlyCodec(dj.Codec, register=False):
-            '''Abstract base - not registered.'''
-            ...
+    ```python
+    class ExternalOnlyCodec(dj.Codec, register=False):
+        '''Abstract base - not registered.'''
+        ...
+    ```
     """
 
     name: str | None = None  # Must be set by concrete subclasses
@@ -520,18 +527,26 @@ def decode_attribute(attr, data, squeeze: bool = False, connection=None):
     Decode raw database value using attribute's codec or native type handling.
 
     This is the central decode function used by all fetch methods. It handles:
-    - Codec chains (e.g., <blob@store> → <hash> → bytes)
+
+    - Codec chains (e.g., ``<blob@store>`` → ``<hash>`` → ``bytes``)
     - Native type conversions (JSON, UUID)
-    - Object storage downloads (via config["download_path"])
+    - Object storage downloads (via ``config["download_path"]``)
 
-    Args:
-        attr: Attribute from the table's heading.
-        data: Raw value fetched from the database.
-        squeeze: If True, remove singleton dimensions from numpy arrays.
-        connection: Connection instance for config access. If provided,
-            ``connection._config`` is passed to codecs via the key dict.
+    Parameters
+    ----------
+    attr : Attribute
+        Attribute from the table's heading.
+    data : any
+        Raw value fetched from the database.
+    squeeze : bool, optional
+        If True, remove singleton dimensions from numpy arrays.
+    connection : Connection, optional
+        Connection instance for config access. If provided,
+        ``connection._config`` is passed to codecs via the key dict.
 
-    Returns:
+    Returns
+    -------
+    any
         Decoded Python value.
     """
     import json