docs: show full field descriptions for SDK parameter types

Author: sid-rl

docs/conf.py

@@ -7,7 +7,8 @@
 
 import os
 import sys
-from typing import Any
+import pkgutil
+from typing import Any, get_type_hints
 
 # Add the src directory to the path so we can import the package
 sys.path.insert(0, os.path.abspath("../src"))
@@ -59,6 +60,87 @@
 autodoc_typehints_description_target = "documented"
 
 
+# -- Patches -----------------------------------------------------------------
+
+
+def _patch_autotypeddict_inherited_docstrings() -> None:
+    """Patch autotypeddict to include field docstrings from parent TypedDicts.
+
+    sphinx_toolbox's sort_members only scans self.object.__module__ for field
+    docstrings (autotypeddict.py:381-384). SDK TypedDicts like SDKDevboxCreateParams
+    inherit fields from types in other modules (e.g. DevboxCreateParams), so those
+    descriptions are lost. This patch collects docstrings from the full
+    __orig_bases__ chain.
+
+    Upstream bug: https://github.com/sphinx-doc/sphinx/issues/9290
+    """
+    from sphinx.errors import PycodeError
+    from sphinx.pycode import ModuleAnalyzer
+    from sphinx_toolbox.more_autodoc.autotypeddict import TypedDictDocumenter
+
+    def _collect_field_docstrings(cls: type) -> dict[str, list[str]]:
+        result: dict[str, list[str]] = {}
+        visited: set[type] = set()
+
+        def _walk(klass: type) -> None:
+            if klass in visited or not hasattr(klass, "__annotations__"):
+                return
+            visited.add(klass)
+            try:
+                for (_, fname), doc in ModuleAnalyzer.for_module(klass.__module__).find_attr_docs().items():
+                    if fname not in result:
+                        result[fname] = doc
+            except PycodeError:
+                pass
+            for base in getattr(klass, "__orig_bases__", []):
+                if isinstance(base, type):
+                    _walk(base)
+
+        _walk(cls)
+        return result
+
+    def _patched_sort_members(
+        self: TypedDictDocumenter,
+        documenters: list[tuple[Any, bool]],
+        order: str,
+    ) -> list[tuple[Any, bool]]:
+        documenters = super(TypedDictDocumenter, self).sort_members(documenters, order)
+        docstrings = _collect_field_docstrings(self.object)
+
+        required_keys: list[str] = []
+        optional_keys: list[str] = []
+        types = get_type_hints(self.object)
+
+        for d in documenters:
+            name = d[0].name.split(".")[-1]
+            if name in self.object.__required_keys__:
+                required_keys.append(name)
+            elif name in self.object.__optional_keys__:
+                optional_keys.append(name)
+
+        sourcename = self.get_sourcename()
+        if required_keys:
+            self.add_line("", sourcename)
+            self.add_line(":Required Keys:", sourcename)
+            self.document_keys(required_keys, types, docstrings)  # pyright: ignore[reportUnknownMemberType]
+            self.add_line("", sourcename)
+        if optional_keys:
+            self.add_line("", sourcename)
+            self.add_line(":Optional Keys:", sourcename)
+            self.document_keys(optional_keys, types, docstrings)  # pyright: ignore[reportUnknownMemberType]
+            self.add_line("", sourcename)
+
+        return []
+
+    TypedDictDocumenter.sort_members = _patched_sort_members  # type: ignore[assignment]
+
+
+_patch_autotypeddict_inherited_docstrings()
+
+
+# -- Dynamic type documentation ----------------------------------------------
+
+
 def _inject_type_submodules(_app: Any, docname: str, source: list[str]) -> None:
     """Auto-generate automodule directives for all type submodules.
 
@@ -70,8 +152,6 @@ def _inject_type_submodules(_app: Any, docname: str, source: list[str]) -> None:
     """
     if docname != "api/types":
         return
-    import pkgutil
-
     import runloop_api_client.types as types_pkg
 
     directives: list[str] = []