[no ci] docs: move autodoc docstring adaptations to separate file

Author: vpratz

docsrc/pre-build.py

@@ -66,6 +66,7 @@ def patch_conf(sourcedir):
         "_static/bayesflow_hor.png",
         "_static/custom.css",
         "sphinxext/override_pst_pagetoc.py",
+        "sphinxext/adapt_autodoc_docstring.py",
     ]
     for path in copy_rel_paths:
         srcfile = cursrc / path

docsrc/source/conf.py

@@ -56,7 +56,8 @@
     "sphinx.ext.intersphinx",
     "sphinx_design",
     "sphinxcontrib.bibtex",
-    "override_pst_pagetoc",
+    "override_pst_pagetoc",  # local, see sphinxext folder
+    "adapt_autodoc_docstring",  # local, see sphinxext folder
 ]
 
 intersphinx_mapping = {
@@ -167,36 +168,3 @@
         current: GitRef = data["current"]
     except LoadError:
         print("sphinx_polyversion could not load. Building single version")
-
-
-def docstring(app, what, name, obj, options, lines):
-    """Adapt autodoc docstring.
-
-    Inherited Keras docstrings do not follow the numpy docstring format.
-    Most noticably, they use Markdown code fences. To improve the situation
-    somewhat, this functions aims to convert fenced code blocks to RST
-    code blocks.
-    """
-    updated_lines = []
-    prefix = ""
-    for line in lines:
-        if line.count("```") == 1:
-            if prefix == "":
-                prefix = "    "
-                updated_lines[-1] = updated_lines[-1] + "::"
-            else:
-                prefix = ""
-            updated_lines.append("\n")
-        else:
-            updated_lines.append(prefix + line)
-    if prefix != "":
-        raise ValueError(
-            f"Uneven number of code fences in docstring:\nwhat='{what}', name='{name}'.\n" + "\n".join(lines)
-        )
-    # overwrite lines list
-    lines.clear()
-    lines += updated_lines
-
-
-def setup(app):
-    app.connect("autodoc-process-docstring", docstring)

docsrc/source/sphinxext/adapt_autodoc_docstring.py

@@ -0,0 +1,31 @@
+def docstring(app, what, name, obj, options, lines):
+    """Adapt autodoc docstring.
+
+    Inherited Keras docstrings do not follow the numpy docstring format.
+    Most noticably, they use Markdown code fences. To improve the situation
+    somewhat, this functions aims to convert fenced code blocks to RST
+    code blocks.
+    """
+    updated_lines = []
+    prefix = ""
+    for line in lines:
+        if line.count("```") == 1:
+            if prefix == "":
+                prefix = "    "
+                updated_lines[-1] = updated_lines[-1] + "::"
+            else:
+                prefix = ""
+            updated_lines.append("\n")
+        else:
+            updated_lines.append(prefix + line)
+    if prefix != "":
+        raise ValueError(
+            f"Uneven number of code fences in docstring:\nwhat='{what}', name='{name}'.\n" + "\n".join(lines)
+        )
+    # overwrite lines list
+    lines.clear()
+    lines += updated_lines
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", docstring)