Merge pull request #42 from Loop3D/docstring/numpy-style

Docstring/numpy style

Author: lachlangrose

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

loopstructural/gui/modelling/model_definition/bounding_box.py

@@ -24,9 +24,12 @@ def __init__(self, parent=None, data_manager=None):
         self.data_manager.set_bounding_box_update_callback(self.set_bounding_box)
 
     def set_bounding_box(self, bounding_box):
-        """
-        Set the bounding box values in the UI.
-        :param bounding_box: BoundingBox object with xmin, xmax, ymin, ymax, zmin, zmax attributes.
+        """Populate UI controls with values from a BoundingBox object.
+
+        Parameters
+        ----------
+        bounding_box : object
+            BoundingBox-like object with `origin` and `maximum` sequences of length 3.
         """
         self.originXSpinBox.setValue(bounding_box.origin[0])
         self.maxXSpinBox.setValue(bounding_box.maximum[0])
@@ -36,10 +39,7 @@ def set_bounding_box(self, bounding_box):
         self.maxZSpinBox.setValue(bounding_box.maximum[2])
 
     def useCurrentViewExtent(self):
-        """
-        Use the current view extent from the map canvas.
-        This method should be connected to a button or action in the UI.
-        """
+        """Set bounding box values from the current map canvas view extent."""
         if self.data_manager.map_canvas:
             extent = self.data_manager.map_canvas.extent()
             self.originXSpinBox.setValue(extent.xMinimum())
@@ -50,10 +50,7 @@ def useCurrentViewExtent(self):
             self.maxZSpinBox.setValue(1000)
 
     def selectFromCurrentLayer(self):
-        """
-        Select the bounding box from the current layer.
-        This method should be connected to a button or action in the UI.
-        """
+        """Set bounding box values from the currently selected layer's 3D extent."""
         layer = self.data_manager.map_canvas.currentLayer()
         if layer:
             extent = layer.extent3D()

loopstructural/gui/modelling/stratigraphic_column/stratigraphic_column.py

@@ -14,10 +14,19 @@
 
 
 class StratColumnWidget(QWidget):
-    """In control of building the stratigraphic column
-
-    :param QWidget: _description_
-    :type QWidget: _type_
+    """Widget that controls building the stratigraphic column.
+
+    Parameters
+    ----------
+    parent : QWidget, optional
+        Parent widget, by default None.
+    data_manager : object
+        Data manager instance used to manage the stratigraphic column. Must be provided.
+
+    Notes
+    -----
+    The widget updates its display based on the data_manager's stratigraphic column
+    and registers a callback via data_manager.set_stratigraphic_column_callback.
     """
 
     def __init__(self, parent=None, data_manager=None):

loopstructural/gui/modelling/stratigraphic_column/stratigraphic_unit.py

@@ -40,18 +40,19 @@ def name(self, value: str):
         self._name = str(value)
 
     def set_thickness(self, thickness: float):
-        """
-        Set the thickness of the stratigraphic unit.
-        :param thickness: The thickness value to set.
+        """Set the thickness of the stratigraphic unit.
+
+        Parameters
+        ----------
+        thickness : float
+            The thickness value to set.
         """
         self.thickness = thickness
         self.spinBoxThickness.setValue(thickness)
         self.validateFields()
 
     def onColourSelectClicked(self):
-        """
-        Open a color dialog to select a color for the stratigraphic unit.
-        """
+        """Open a color dialog to select a color for the stratigraphic unit."""
         from PyQt5.QtWidgets import QColorDialog
 
         color = QColorDialog.getColor()
@@ -60,19 +61,19 @@ def onColourSelectClicked(self):
         self.buttonColor.setStyleSheet(f"background-color: {self.colour};")
 
     def onThicknessChanged(self, thickness: float):
-        """
-        Update the thickness of the stratigraphic unit.
-        :param thickness: The new thickness value.
+        """Handle changes to the thickness spinbox.
+
+        Parameters
+        ----------
+        thickness : float
+            The new thickness value.
         """
         self.thickness = thickness
         self.validateFields()
         self.thicknessChanged.emit(thickness)
 
     def onNameChanged(self):
-        """
-        Update the name of the stratigraphic unit.
-        :param name: The new name value.
-        """
+        """Handle name edit completion and emit nameChanged if modified."""
         name = self.lineEditName.text().strip()
         if name != self.name:
             self.name = name
@@ -84,9 +85,7 @@ def request_delete(self):
         self.deleteRequested.emit(self)
 
     def validateFields(self):
-        """
-        Validate the fields and update the widget's appearance.
-        """
+        """Validate the widget fields and update UI hints."""
         # Reset all styles first
         self.lineEditName.setStyleSheet("")
         self.spinBoxThickness.setStyleSheet("")
@@ -101,9 +100,12 @@ def validateFields(self):
             self.spinBoxThickness.setToolTip("Thickness must be greater than zero.")
 
     def setData(self, data: Optional[dict] = None):
-        """
-        Set the data for the stratigraphic unit widget.
-        :param data: A dictionary containing 'name' and 'colour' keys.
+        """Set the data for the stratigraphic unit widget.
+
+        Parameters
+        ----------
+        data : dict or None
+            Dictionary containing 'name' and 'colour' keys. If None, defaults are used.
         """
         if data:
             self.name = str(data.get("name", ""))
@@ -119,9 +121,12 @@ def setData(self, data: Optional[dict] = None):
         self.validateFields()
 
     def getData(self) -> dict:
-        """
-        Get the data from the stratigraphic unit widget.
-        :return: A dictionary containing 'name', 'colour', and 'thickness'.
+        """Return the widget data as a dictionary.
+
+        Returns
+        -------
+        dict
+            Dictionary containing 'uuid', 'name', 'colour', and 'thickness'.
         """
         return {
             "uuid": self.uuid,

loopstructural/gui/modelling/stratigraphic_column/unconformity.py

@@ -29,9 +29,12 @@ def request_delete(self):
         self.deleteRequested.emit(self)
 
     def setData(self, data: Optional[dict] = None):
-        """
-        Set the data for the unconformity widget.
-        :param data: A dictionary containing 'unconformity_type' key.
+        """Set the data for the unconformity widget.
+
+        Parameters
+        ----------
+        data : dict or None
+            Dictionary containing 'unconformity_type' key. If None, defaults are used.
         """
         if data:
             self.unconformity_type = data.get("unconformity_type", "")

loopstructural/gui/visualisation/feature_list_widget.py

@@ -57,10 +57,12 @@ def _get_vector_scale(self, scale: Optional[Union[float, int]] = None) -> float:
         return scale
 
     def add_feature(self, feature):
-        """Add a feature to the feature list.
+        """Add a feature to the feature list widget.
 
-        :param feature: The feature to add.
-        :type feature: Feature
+        Parameters
+        ----------
+        feature : Feature
+            The feature object to add to the list.
         """
         featureItem = QTreeWidgetItem(self.treeWidget)
         featureItem.setText(0, feature.name)