From 2a53c1638c3f740a3b1923a61db26be4e97a41f5 Mon Sep 17 00:00:00 2001
From: Liam Huber <liamhuber@greyhavensolutions.com>
Date: Sat, 7 Sep 2024 14:42:55 -0700
Subject: [PATCH] [patch] Extend automatic macro and function node
 documentation (#447)

* [patch] Extend automatic macro and function node documentation

To scrape not just the docstring, but the signature and source code as well

* Format black

---------

Co-authored-by: pyiron-runner <pyiron@mpie.de>
---
 pyiron_workflow/mixin/preview.py  | 32 +++++++++++++++++++++++++++++++
 pyiron_workflow/nodes/function.py |  4 +++-
 pyiron_workflow/nodes/macro.py    |  2 +-
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/pyiron_workflow/mixin/preview.py b/pyiron_workflow/mixin/preview.py
index a4c0bf84d..41dc8417f 100644
--- a/pyiron_workflow/mixin/preview.py
+++ b/pyiron_workflow/mixin/preview.py
@@ -286,6 +286,38 @@ def _validate_return_count(cls):
                     f"present, " + error_suffix
                 )
 
+    @staticmethod
+    def _io_defining_documentation(io_defining_function: callable, title: str):
+        """
+        A helper method for building a docstring for classes that have their IO defined
+        by some function.
+        """
+        try:
+            signature = str(inspect.signature(io_defining_function))
+        except Exception as e:
+            signature = f"SIGNATURE NOT AVAILABLE -- {type(e).__name__}: {e}"
+
+        try:
+            source = inspect.getsource(io_defining_function)
+        except Exception as e:
+            source = f"SOURCE NOT AVAILABLE -- {type(e).__name__}: {e}"
+
+        doc = (
+            "" if io_defining_function.__doc__ is None else io_defining_function.__doc__
+        )
+
+        docs = f"{title.upper()} INFO:\n\n"
+        docs += "Signature:\n\n"
+        docs += signature
+        docs += "\n\n"
+        docs += "Docstring:\n\n"
+        docs += doc
+        docs += "\n"
+        docs += "Source:\n\n"
+        docs += source
+        docs += "\n"
+        return docs
+
 
 def no_output_validation_warning(cls: type):
     return (
diff --git a/pyiron_workflow/nodes/function.py b/pyiron_workflow/nodes/function.py
index 84ceafcc0..92309db75 100644
--- a/pyiron_workflow/nodes/function.py
+++ b/pyiron_workflow/nodes/function.py
@@ -380,7 +380,9 @@ def function_node_factory(
             "__qualname__": node_function.__qualname__,
             "_output_labels": None if len(output_labels) == 0 else output_labels,
             "_validate_output_labels": validate_output_labels,
-            "__doc__": node_function.__doc__,
+            "__doc__": Function._io_defining_documentation(
+                node_function, "node_function"
+            ),
             "use_cache": use_cache,
         },
         {},
diff --git a/pyiron_workflow/nodes/macro.py b/pyiron_workflow/nodes/macro.py
index a16aef288..e193beceb 100644
--- a/pyiron_workflow/nodes/macro.py
+++ b/pyiron_workflow/nodes/macro.py
@@ -494,7 +494,7 @@ def macro_node_factory(
             "__qualname__": graph_creator.__qualname__,
             "_output_labels": None if len(output_labels) == 0 else output_labels,
             "_validate_output_labels": validate_output_labels,
-            "__doc__": graph_creator.__doc__,
+            "__doc__": Macro._io_defining_documentation(graph_creator, "graph_creator"),
             "use_cache": use_cache,
         },
         {},