docs: Improve docstring formatting and add Sphinx processing extensions

Author: thiswillbeyourgithub

docs/source/_ext/better_docstring.py

@@ -0,0 +1,27 @@
+from sphinx.ext.autodoc import between
+
+def setup(app):
+    # Register a priority handler for docstrings
+    app.connect('autodoc-process-docstring', process_docstring)
+    return {'version': '1.0', 'parallel_read_safe': True}
+
+def process_docstring(app, what, name, obj, options, lines):
+    """Process docstrings to ensure they are properly formatted."""
+    # Remove empty lines at start
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    # Remove empty lines at end
+    while lines and not lines[-1].strip():
+        lines.pop()
+    
+    # Ensure there's spacing between sections
+    new_lines = []
+    in_section = False
+    for line in lines:
+        if line.strip() and line[0].isalpha() and ':' in line:
+            if in_section:
+                new_lines.append('')
+            in_section = True
+        new_lines.append(line)
+    
+    lines[:] = new_lines

docs/source/conf.py

@@ -25,6 +25,7 @@
     'sphinx.ext.viewcode',
     'myst_parser',  # for markdown support
     'raw_docstring',
+    'better_docstring',
     'sphinx.ext.autosectionlabel'
 ]
 
@@ -49,6 +50,8 @@
 napoleon_use_ivar = True
 napoleon_use_param = True
 napoleon_use_rtype = True
+napoleon_attr_annotations = True
+napoleon_preprocess_types = True
 
 templates_path = ['_templates']
 exclude_patterns = []

wdoc/utils/interact.py

@@ -19,7 +19,14 @@
 
 @optional_typecheck
 def get_toolbar_text(settings: dict) -> Any:
-    "parsed settings to be well displayed in the prompt toolbar"
+    """Parse settings for display in the prompt toolbar.
+    
+    Args:
+        settings (dict): Dictionary containing the current settings
+        
+    Returns:
+        Any: Formatted text suitable for display in the toolbar
+    """
     out = []
     keys = sorted(list(settings.keys()))
     for k in keys:
@@ -85,7 +92,14 @@ def get_completions(self, document, complete_event):
 
 @optional_typecheck
 def show_help() -> None:
-    "display CLI help"
+    """Display CLI help information.
+    
+    This function displays the CLI help information by formatting and showing
+    the docstring from the ask_user function.
+    
+    Returns:
+        None
+    """
     md_printer(dedent(ask_user.__doc__).strip())