From 82f7125e04b2ae7c6d6ef7c4572aca7de77025ee Mon Sep 17 00:00:00 2001
From: Joe <josephnumainville@deephaven.io>
Date: Tue, 29 Oct 2024 10:32:03 -0500
Subject: [PATCH] fix: Incorrect output in autodoc (#960)

Autodoc output was not as expected
Additionally, description was still in the ParamTable object, but can
have newlines, so rendering broke.
---
 sphinx_ext/deephaven_autodoc.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/sphinx_ext/deephaven_autodoc.py b/sphinx_ext/deephaven_autodoc.py
index 5d7abc703..56e6e946b 100644
--- a/sphinx_ext/deephaven_autodoc.py
+++ b/sphinx_ext/deephaven_autodoc.py
@@ -33,14 +33,13 @@ class FunctionMetadata(TypedDict):
     name: str
 
 
-# total is False to allow for popping some keys
 class SignatureData(TypedDict):
     parameters: Params
-    return_description: str
-    return_type: str
+    return_description: NotRequired[str]
+    return_type: NotRequired[str]
     module_name: str
     name: str
-    description: str
+    description: NotRequired[str]
 
 
 SignatureValue = Union[str, Params]
@@ -306,15 +305,17 @@ def to_mdx(node: sphinx.addnodes.desc) -> docutils.nodes.comment:
     """
     result = extract_desc_data(node)
 
-    dat = json.dumps(result)
+    # these need to be popped in case they have newlines which will break ParamTable rendering
+    return_description = result.pop("return_description")
+    return_type = result.pop("return_type")
+    description = result.pop("description")
 
-    return_description = result["return_description"]
-    return_type = result["return_type"]
+    dat = json.dumps(result)
 
     autofunction_markdown = (
         f"{AUTOFUNCTION_COMMENT_PREFIX}"
-        rf"{return_description}<br /><br />"
-        rf"**Returns:** {return_type}<br /><br />"
+        rf"{description}<br /><br />"
+        rf"**Returns:** `{return_type}` {return_description}<br /><br />"
         rf"<ParamTable param={{{dat}}} />"
     )