From 0dd7aeb687aea562701368c8987c3831db3dcc00 Mon Sep 17 00:00:00 2001
From: Joe <josephnumainville@deephaven.io>
Date: Tue, 15 Oct 2024 12:20:20 -0500
Subject: [PATCH] fix: Don't strip new lines in dhautofunction (#805)

No longer removes newlines, residual from before we were using a table
---
 sphinx_ext/deephaven_autodoc.py   | 23 +++++++++++++++++------
 sphinx_ext/make_docs_utilities.py |  8 ++++++--
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/sphinx_ext/deephaven_autodoc.py b/sphinx_ext/deephaven_autodoc.py
index 4ed206e33..4cfdcea49 100644
--- a/sphinx_ext/deephaven_autodoc.py
+++ b/sphinx_ext/deephaven_autodoc.py
@@ -33,6 +33,7 @@ class FunctionMetadata(TypedDict):
     name: str
 
 
+# total is False to allow for popping some keys
 class SignatureData(TypedDict):
     parameters: Params
     return_description: str
@@ -44,6 +45,8 @@ class SignatureData(TypedDict):
 
 SignatureValue = Union[str, Params]
 
+AUTOFUNCTION_COMMENT_PREFIX = "AutofunctionCommentPrefix:"
+
 
 def extract_parameter_defaults(
     node: sphinx.addnodes.desc_parameterlist,
@@ -101,9 +104,9 @@ def extract_list_item(node: docutils.nodes.list_item) -> ParamData:
     Returns:
         The param data
     """
-    field = node.astext().replace("\n", " ")
+    field = node.astext().replace("\n", "<br />")
     try:
-        match = re.match(r"(.+) \((.*)\) -- (.+)", field)
+        match = re.match(r"(.+?) \((.*?)\) -- (.+)", field, re.DOTALL)
         if match is None:
             raise ValueError(
                 f"Could not match {field} to extract param data. "
@@ -154,7 +157,7 @@ def extract_field_body(
         # this is still a parameter, likely the only one in its signature
         return [extract_list_item(child)]
     elif is_paragraph:
-        return node.astext().replace("\n", " ")
+        return node.astext().replace("\n", "<br />")
     elif isinstance(child, docutils.nodes.bullet_list):
         return extract_list_items(child)
     raise ValueError(
@@ -225,7 +228,7 @@ def extract_content_data(
         if isinstance(child_node, docutils.nodes.field_list):
             result.update(extract_field_list(child_node))
         elif isinstance(child_node, docutils.nodes.paragraph):
-            result["description"] = child_node.astext().replace("\n", " ")
+            result["description"] = child_node.astext().replace("\n", "<br />")
 
     return result
 
@@ -305,11 +308,19 @@ def to_mdx(node: sphinx.addnodes.desc) -> docutils.nodes.comment:
 
     dat = json.dumps(result)
 
-    param_table = f"<ParamTable param={{{dat}}} />"
+    return_description = result["return_description"]
+    return_type = result["return_type"]
+
+    autofunction_markdown = (
+        f"{AUTOFUNCTION_COMMENT_PREFIX}"
+        rf"{return_description}<br /><br />"
+        rf"**Returns:** {return_type}<br /><br />"
+        rf"<ParamTable param={{{dat}}} />"
+    )
 
     # This is a little hacky, but this way the markdown renderer will not escape the special characters
     # such as * and \. The comment markers will be removed by make_docs.py.
-    return docutils.nodes.comment("", "", docutils.nodes.raw("", param_table))
+    return docutils.nodes.comment("", "", docutils.nodes.raw("", autofunction_markdown))
 
 
 class DeephavenAutodoc(AutodocDirective):
diff --git a/sphinx_ext/make_docs_utilities.py b/sphinx_ext/make_docs_utilities.py
index ec0c4b2e0..f15c5d760 100644
--- a/sphinx_ext/make_docs_utilities.py
+++ b/sphinx_ext/make_docs_utilities.py
@@ -4,6 +4,7 @@
 import os
 import contextlib
 from typing import IO, Generator
+from deephaven_autodoc import AUTOFUNCTION_COMMENT_PREFIX
 
 BUILT_DOCS = "docs/build/markdown"
 
@@ -111,12 +112,15 @@ def remove_paramtable_comment(
     Returns:
         str: The line with the comment markers removed
     """
-    if line.startswith("<!-- <ParamTable param={{") and line.endswith("}} /> -->\n"):
+    if line.startswith(f"<!-- {AUTOFUNCTION_COMMENT_PREFIX}") and line.endswith(
+        "}} /> -->\n"
+    ):
         # remove the comment markers
         # these are added in deephaven_autodoc.py to prevent special characters from being escaped
         # by the markdown renderer
-        line = line.replace("<!-- ", "")
+        line = line.replace(f"<!-- {AUTOFUNCTION_COMMENT_PREFIX}", "")
         line = line.replace(" -->", "")
+        line = line.replace("<br />", "\n")
     return line