From 3fb107783d5e204557825c763fcb5adc94ffe37e Mon Sep 17 00:00:00 2001
From: Maciej Bartkowiak <maciej.bartkowiak@stfc.ac.uk>
Date: Thu, 18 Apr 2024 17:26:43 +0100
Subject: [PATCH] Split the code of Configurable.build_doc into several methods

---
 MDANSE/Src/MDANSE/Framework/Configurable.py   | 113 +++++++-----------
 .../Src/MDANSE_GUI/Tabs/Models/JobTree.py     |   2 +-
 2 files changed, 42 insertions(+), 73 deletions(-)

diff --git a/MDANSE/Src/MDANSE/Framework/Configurable.py b/MDANSE/Src/MDANSE/Framework/Configurable.py
index bce864e8de..5946998391 100644
--- a/MDANSE/Src/MDANSE/Framework/Configurable.py
+++ b/MDANSE/Src/MDANSE/Framework/Configurable.py
@@ -210,39 +210,7 @@ def __str__(self):
         return "\n".join(self._info)
 
     @classmethod
-    def build_doc(cls):
-        """
-        Return the documentation about a configurable class based on its configurators contents.
-
-        :param cls: the configurable class for which documentation should be built
-        :type cls: an instance of MDANSE.Framework.Configurable.Configurable derived class
-
-        :return: the documentation about the configurable class
-        :rtype: str
-        """
-        from MDANSE.Framework.Configurators.IConfigurator import IConfigurator
-
-        settings = getattr(cls, "settings", {})
-
-        if not isinstance(settings, dict):
-            raise ConfigurationError(
-                "Invalid type for settings: must be a mapping-like object"
-            )
-
-        doclist = []
-
-        for name, (typ, kwds) in list(settings.items()):
-            cfg = IConfigurator.create(typ, name, **kwds)
-            descr = kwds.get("description", "")
-            descr += "\n" + str(cfg.__doc__)
-            doclist.append(
-                {
-                    "Configurator": name,
-                    "Default value": repr(cfg.default),
-                    "Description": descr,
-                }
-            )
-
+    def build_doc_example(cls):
         docstring = ":Example:\n\n"
         docstring += ">>> \n"
         docstring += ">>> \n"
@@ -253,8 +221,11 @@ def build_doc(cls):
         docstring += ">>> job = IJob.create(%r)\n" % cls.__name__
         docstring += ">>> job.setup(parameters)\n"
         docstring += ">>> job.run()\n"
+        return docstring
 
-        docstring += "\n**Job input configurators:** \n\n"
+    @classmethod
+    def build_doc_texttable(cls, doclist):
+        docstring = "\n**Job input configurators:** \n\n"
 
         columns = ["Configurator", "Default value", "Description"]
 
@@ -314,11 +285,41 @@ def build_doc(cls):
             )
 
         docstring += "\n"
+        return docstring
 
+    @classmethod
+    def build_doc_htmltable(cls, doclist):
+        docstring = "\n**Job input configurators:**"
+
+        columns = ["Configurator", "Default value", "Description"]
+
+        for v in doclist:
+            # Case of Description field: has to be splitted and parsed for inserting sphinx "|" keyword for multiline
+            v["Description"] = v["Description"].strip()
+            v["Description"] = v["Description"].split("\n")
+            v["Description"] = ["" + vv.strip() for vv in v["Description"]]
+
+        docstring += "<table>\n"
+        docstring += "<tr>"
+        for col in columns:
+            docstring += f"<th>{col}</th>"
+        docstring += "</tr>\n"
+
+        for v in doclist:
+            docstring += "<tr>"
+            for item in [
+                v["Configurator"],
+                v["Default value"],
+                v["Description"][0],
+            ]:
+                docstring += f"<td>{item}</td>"
+            docstring += "</tr>\n"
+
+        docstring += "</table>\n"
         return docstring
 
     @classmethod
-    def build_html_doc(cls):
+    def build_doc(cls, use_html_table=False):
         """
         Return the documentation about a configurable class based on its configurators contents.
 
@@ -351,44 +352,12 @@ def build_html_doc(cls):
                 }
             )
 
-        docstring = ":Example:\n\n"
-        docstring += ">>> \n"
-        docstring += ">>> \n"
-        docstring += ">>> parameters = {}\n"
-        for k, v in list(cls.get_default_parameters().items()):
-            docstring += ">>> parameters[%r]=%r\n" % (k, v)
-        docstring += ">>> \n"
-        docstring += ">>> job = IJob.create(%r)\n" % cls.__name__
-        docstring += ">>> job.setup(parameters)\n"
-        docstring += ">>> job.run()\n"
-
-        docstring += "\n**Job input configurators:** \n\n"
-
-        columns = ["Configurator", "Default value", "Description"]
+        docstring = cls.build_doc_example()
 
-        for v in doclist:
-            # Case of Description field: has to be splitted and parsed for inserting sphinx "|" keyword for multiline
-            v["Description"] = v["Description"].strip()
-            v["Description"] = v["Description"].split("\n")
-            v["Description"] = ["" + vv.strip() for vv in v["Description"]]
-
-        docstring += "<table>\n"
-        docstring += "<tr>"
-        for col in columns:
-            docstring += f"<th>{col}</th>"
-        docstring += "</tr>\n"
-
-        for v in doclist:
-            docstring += "<tr>"
-            for item in [
-                v["Configurator"],
-                v["Default value"],
-                v["Description"][0],
-            ]:
-                docstring += f"<td>{item}</td>"
-            docstring += "</tr>\n"
-
-        docstring += "</table>\n"
+        if use_html_table:
+            docstring += cls.build_doc_htmltable(doclist)
+        else:
+            docstring += cls.build_doc_texttable(doclist)
 
         return docstring
 
diff --git a/MDANSE_GUI/Src/MDANSE_GUI/Tabs/Models/JobTree.py b/MDANSE_GUI/Src/MDANSE_GUI/Tabs/Models/JobTree.py
index 8c8fe21028..0d404f3cb5 100644
--- a/MDANSE_GUI/Src/MDANSE_GUI/Tabs/Models/JobTree.py
+++ b/MDANSE_GUI/Src/MDANSE_GUI/Tabs/Models/JobTree.py
@@ -81,7 +81,7 @@ def createNode(self, name: str, thing, filter: str = ""):
         self._values[new_number] = thing
         self._docstrings[new_number] = thing.__doc__
         try:
-            self._docstrings[new_number] += "\n" + thing.build_html_doc()
+            self._docstrings[new_number] += "\n" + thing.build_doc(use_html_table=True)
         except AttributeError:
             pass
         except TypeError: