🎨 Update Sphinx formatting

Author: shnizzedy

docs/_sources/conf.py

@@ -12,17 +12,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import m2r
 import os
 import re
-import semver
 import sys
 
-from CPAC import __version__
 from dateutil import parser as dparser
+from CPAC import __version__
+from CPAC.utils.monitoring import custom_logging
 from github import Github
 from github.GithubException import RateLimitExceededException, \
     UnknownObjectException
+import m2r
+import semver
 from pybtex.plugin import register_plugin
 
 sys.path.append(os.path.dirname(__file__))
@@ -571,45 +572,59 @@ def _unireplace(release_note, unireplace):
 ) if len(gh_tags) >= 5 else ""
 
 
-def format_node_block_docstrings(app, what, name, obj, options, lines):
-    _ = (app, name, obj, options)
-    if what in ["function"]:
-        indent = 0
-        insert_at = None
-        first_to_del = None
-        nevermore = False
-        for i, line in enumerate(lines):
-            if nevermore and not line.strip():
-                first_to_del = i + 1
-                nevermore = False
-            if line.lstrip().startswith("Node Block:"):
-                insert_at = i + 1
-                indent = 3
-            elif indent == 0 and re.match(r"\s*{['\"]name['\"]:", line):
+def autodoc_process_docstring(app, what, name, obj, options, lines) -> None:
+    """Modify docstrings before parsing RST"""
+    # pylint: disable=too-many-arguments,unused-argument
+    initialize_factory()
+    if what == "function":
+        format_node_block_docstrings(lines)
+
+
+def format_node_block_docstrings(lines: list) -> None:
+    """Format Node Block docstring dictionaries as Python code blocks
+
+    Parameters
+    ----------
+    lines : list
+        modified in-place
+    """
+    indent = 0
+    insert_at = None
+    first_to_del = None
+    nevermore = False
+    for i, line in enumerate(lines):
+        if nevermore and not line.strip():
+            first_to_del = i + 1
+            nevermore = False
+        if line.lstrip().startswith("Node Block:"):
+            insert_at = i + 1
+            indent = 3
+        else:
+            if indent == 0 and re.match(r"\s*{['\"]name['\"]:", line):
                 insert_at = i
                 indent = 3
-            else:
-                lines[i] = f'{" " * indent}{line}'
-            if re.match(r"\s*{['\"]outputs['\"]:", line):
-                nevermore = True
-        if first_to_del is not None:
-            del lines[first_to_del:]
-        if insert_at is not None:
-            lines.insert(insert_at, '')
-            lines.insert(insert_at, ".. code-block:: Python")
-            print('\n'.join([f'|{line}|' for line in lines]))
-
-
-def setup(app):
-    from CPAC.utils.monitoring import custom_logging
-
-    # initilaize class to make factory functions available to Sphinx
-    ml = custom_logging.MockLogger('test', 'test.log', 0, '/tmp')
+            lines[i] = f'{" " * indent}{line}'
+        if re.match(r"\s*{['\"]outputs['\"]:", line):
+            nevermore = True
+    if first_to_del is not None:
+        del lines[first_to_del:]
+    if insert_at is not None:
+        lines.insert(insert_at, '')
+        lines.insert(insert_at, ".. code-block:: Python")
+
+
+def initialize_factory() -> None:
+    """Initilaize class to make factory functions available to Sphinx"""
+    mocklogger = custom_logging.MockLogger('test', 'test.log', 0, '/tmp')
     for method in [
         method for method in
-        set(dir(ml)) - set(dir(custom_logging.MockLogger)) if
+        set(dir(mocklogger)) - set(dir(custom_logging.MockLogger)) if
         method not in ['name', 'handlers']
     ]:
-        setattr(custom_logging.MockLogger, method, getattr(ml, method))
+        setattr(custom_logging.MockLogger, method,
+                getattr(mocklogger, method))
+
 
-    app.connect('autodoc-process-docstring', format_node_block_docstrings)
+def setup(app) -> None:
+    """Extend Sphinx"""
+    app.connect('autodoc-process-docstring', autodoc_process_docstring)