Docstring/numpy style

loopstructural/__about__.py

@@ -1,7 +1,8 @@
 #! python3
 
-"""Metadata about the package to easily retrieve informations about it.
-See: https://packaging.python.org/guides/single-sourcing-package-version/
+"""Package metadata.
+
+Contains package metadata constants used by the plugin (title, icon, etc.).
 """
 
 # ############################################################################
@@ -36,13 +37,17 @@
 # ########## Functions #############
 # ##################################
 def plugin_metadata_as_dict() -> dict:
-    """Read plugin metadata.txt and returns it as a Python dict.
+    """Read plugin metadata.txt and return it as a Python dict.
 
-    Raises:
-        IOError: if metadata.txt is not found
+    Raises
+    ------
+    IOError
+        If metadata.txt is not found.
 
-    Returns:
-        dict: dict of dicts.
+    Returns
+    -------
+    dict
+        Metadata sections as nested dictionaries.
 
     """
     config = ConfigParser()

loopstructural/__init__.py

@@ -1,5 +1,10 @@
 #! python3
 
+"""LoopStructural QGIS plugin package.
+
+Utilities and metadata for the LoopStructural QGIS plugin.
+"""
+
 # ----------------------------------------------------------
 # Copyright (C) 2015 Martin Dobias
 # ----------------------------------------------------------
@@ -15,8 +20,15 @@
 def classFactory(iface):
     """Load the plugin class.
 
-    :param iface: A QGIS interface instance.
-    :type iface: QgsInterface
+    Parameters
+    ----------
+    iface : QgsInterface
+        A QGIS interface instance provided by QGIS when loading plugins.
+
+    Returns
+    -------
+    LoopstructuralPlugin
+        An instance of the plugin class initialized with `iface`.
     """
     from .plugin_main import LoopstructuralPlugin
 

loopstructural/gui/__init__.py

@@ -0,0 +1,7 @@
+#! python3
+"""GUI package for the LoopStructural QGIS plugin.
+
+Contains widgets, dialogs and visualisation helpers used by the plugin UI.
+"""
+
+# Re-export commonly used GUI classes if needed

loopstructural/gui/dlg_settings.py

@@ -80,10 +80,7 @@ def __init__(self, parent):
         self.load_settings()
 
     def apply(self):
-        """Called to permanently apply the settings shown in the options page (e.g. \
-        save them to QgsSettings objects). This is usually called when the options \
-        dialog is accepted.
-        """
+        """Apply settings from the form and persist them to QgsSettings."""
         settings = self.plg_settings.get_plg_settings()
 
         # misc
@@ -104,7 +101,7 @@ def apply(self):
             )
 
     def load_settings(self):
-        """Load options from QgsSettings into UI form."""
+        """Load options from QgsSettings into the UI form."""
         settings = self.plg_settings.get_plg_settings()
 
         # global
@@ -117,7 +114,7 @@ def load_settings(self):
         self.npw_spin_box.setValue(settings.interpolator_npw)
 
     def reset_settings(self):
-        """Reset settings to default values (set in preferences.py module)."""
+        """Reset settings in the UI and persisted settings to plugin defaults."""
         default_settings = PlgSettingsStructure()
 
         # dump default settings into QgsSettings
@@ -130,41 +127,57 @@ def reset_settings(self):
 class PlgOptionsFactory(QgsOptionsWidgetFactory):
     """Factory for options widget."""
 
-    def __init__(self):
-        """Constructor."""
+    def __init__(self, *args, **kwargs):
+        """Initialize the options factory.
+
+        Parameters
+        ----------
+        *args, **kwargs
+            Forwarded to base factory initializer.
+        """
         super().__init__()
 
-    def icon(self) -> QIcon:
-        """Returns plugin icon, used to as tab icon in QGIS options tab widget.
+    def icon(self):
+        """Return the icon used for the options page.
 
-        :return: _description_
-        :rtype: QIcon
+        Returns
+        -------
+        QIcon
+            Icon for the options page.
         """
         return QIcon(str(__icon_path__))
 
     def createWidget(self, parent) -> ConfigOptionsPage:
         """Create settings widget.
 
-        :param parent: Qt parent where to include the options page.
-        :type parent: QObject
+        Parameters
+        ----------
+        parent : QObject
+            Qt parent where to include the options page.
 
-        :return: options page for tab widget
-        :rtype: ConfigOptionsPage
+        Returns
+        -------
+        ConfigOptionsPage
+            Instantiated options page.
         """
         return ConfigOptionsPage(parent)
 
     def title(self) -> str:
-        """Returns plugin title, used to name the tab in QGIS options tab widget.
+        """Plugin title used to name options tab.
 
-        :return: plugin title from about module
-        :rtype: str
+        Returns
+        -------
+        str
+            Plugin title string.
         """
         return __title__
 
     def helpId(self) -> str:
-        """Returns plugin help URL.
+        """Plugin help URL.
 
-        :return: plugin homepage url from about module
-        :rtype: str
+        Returns
+        -------
+        str
+            URL of the plugin homepage.
         """
         return __uri_homepage__

loopstructural/gui/loop_widget.py

@@ -1,12 +1,32 @@
+#! python3
+"""Main Loop widget used in the plugin dock.
+
+This module exposes `LoopWidget` which provides the primary user
+interface for interacting with LoopStructural features inside QGIS.
+"""
+
 from PyQt5.QtWidgets import QTabWidget, QVBoxLayout, QWidget
 from .modelling.modelling_widget import ModellingWidget
 from .visualisation.visualisation_widget import VisualisationWidget
 
 
 class LoopWidget(QWidget):
+    """Main dock widget that contains modelling and visualisation tools.
+
+    The widget composes multiple tabs and controls used to construct and
+    inspect geological models.
+    """
+
     def __init__(
         self, parent=None, *, mapCanvas=None, logger=None, data_manager=None, model_manager=None
     ):
+        """Initialize the Loop widget.
+
+        Parameters
+        ----------
+        *args, **kwargs
+            Forwarded to the parent widget constructor.
+        """
         super().__init__(parent)
         self.mapCanvas = mapCanvas
         self.logger = logger