Enable docsting linting in ruff and cleans up some docstrings

Author: StephenNneji

packaging/build_exe.py

@@ -57,7 +57,7 @@
 
 
 def build_exe():
-    """Builds the executable for the rascal-2 application"""
+    """Builds the executable for the rascal-2 application."""
     os.environ["DELAY_MATLAB_START"] = "1"
     work_path = PACKAGING_PATH / "temp"
     dist_path = PACKAGING_PATH / "bundle"

pyproject.toml

@@ -28,8 +28,15 @@ line-length = 120
 extend-exclude = ["examples/*", "doc/*"]
 
 [tool.ruff.lint]
-select = ["E", "F", "UP", "B", "SIM", "I", "N", "TD003", "A"]
-ignore = ["SIM108", "N817"]
+select = ["E", "F", "UP", "B", "SIM", "I", "N", "TD003", "A", "D"]
+ignore = ["SIM108", "N817", "D100", "D102", "D104", "D105", "D107", "D203", "D401"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+# ignore docstring lints in the tests and install script
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D101", "D103"]
 
 [tool.ruff.lint.flake8-pytest-style]
 fixture-parentheses = false

rascal2/config.py

@@ -26,7 +26,7 @@
 
 
 def handle_scaling():
-    """Changes settings to handle UI scaling"""
+    """Changes settings to handle UI scaling."""
     if platform.system() == "Windows":
         from ctypes import windll
 
@@ -121,7 +121,7 @@ def get_logger():
 
 
 def log_uncaught_exceptions(exc_type, exc_value, exc_traceback):
-    """Qt slots swallows exceptions but this ensures exceptions are logged"""
+    """Qt slots swallows exceptions but this ensures exceptions are logged."""
     logger = get_logger()
     logger.addHandler(logging.StreamHandler(stream=sys.stderr))  # print emergency crashes to terminal
     logger.critical("An unhandled exception occurred!", exc_info=(exc_type, exc_value, exc_traceback))
@@ -130,7 +130,7 @@ def log_uncaught_exceptions(exc_type, exc_value, exc_traceback):
 
 
 def run_matlab(ready_event, close_event, engine_output):
-    """Start a new matlab engine instance and waits until closed
+    """Start a new matlab engine instance and waits until closed.
 
     Parameters
     ----------
@@ -162,7 +162,7 @@ def run_matlab(ready_event, close_event, engine_output):
 
 
 def get_matlab_engine(engine_ready, engine_output, is_local=False):
-    """Get a MATLAB engine from the MatlabHelper or exception if no engine is available
+    """Get a MATLAB engine from the MatlabHelper or exception if no engine is available.
 
     Parameters
     ----------
@@ -204,7 +204,7 @@ def get_matlab_engine(engine_ready, engine_output, is_local=False):
 
 
 class MatlabHelper:
-    """Helper to start MATLAB on another process"""
+    """Helper to start MATLAB on another process."""
 
     _instance = None
 
@@ -220,7 +220,7 @@ def __new__(cls):
         return cls._instance
 
     def async_start(self):
-        """Start MATLAB on a new process"""
+        """Start MATLAB on a new process."""
         self.manager = mp.Manager()
         self.engine_output = self.manager.list()
 
@@ -257,7 +257,7 @@ def get_local_engine(self):
         return self.__engine
 
     def get_matlab_path(self):
-        """Get MATLAB install directory
+        """Get MATLAB install directory.
 
         Returns
         -------

rascal2/core/commands.py

@@ -12,7 +12,7 @@
 
 @unique
 class CommandID(IntEnum):
-    """Unique ID for undoable commands"""
+    """Unique ID for undoable commands."""
 
     EditControls = 1000
     EditProject = 2000
@@ -76,8 +76,7 @@ def redo(self):
             self.new_result = self.old_result
 
     def mergeWith(self, command):
-        """Merges consecutive Edit controls commands if the attributes are the
-        same."""
+        """Merges consecutive Edit controls commands if the attributes are the same."""
         # We should think about if merging all Edit controls irrespective of
         # attribute is the way to go for UX
         if list(self.new_values.keys()) != list(command.new_values.keys()):
@@ -93,11 +92,13 @@ def mergeWith(self, command):
         return True
 
     def id(self):
-        """Returns ID used for merging commands"""
+        """Returns ID used for merging commands."""
         raise NotImplementedError
 
 
 class EditControls(AbstractModelEdit):
+    """Command for editing an attribute of the controls model."""
+
     attribute = "controls"
 
     @property
@@ -109,6 +110,8 @@ def id(self):
 
 
 class EditProject(AbstractModelEdit):
+    """Command for editing an attribute of the project model."""
+
     attribute = "project"
 
     @property
@@ -204,7 +207,7 @@ def update_calculation_outputs(
         results: ratapi.outputs.Results | ratapi.outputs.BayesResults,
         log: str,
     ):
-        """Updates the project, results and log in the main window model
+        """Updates the project, results and log in the main window model.
 
         Parameters
         ----------

rascal2/core/worker.py

@@ -22,8 +22,7 @@ def __init__(self, func, args):
         self.stopped = False
 
     def run(self):
-        """This function is executed on worker thread when the ``QThread.start``
-        method is called."""
+        """Execute function on worker thread when the start method is called."""
         if self.stopped:
             return
 

rascal2/dialogs/about_dialog.py

@@ -10,9 +10,16 @@
 
 
 class AboutDialog(QtWidgets.QDialog):
+    """Dialog to display RasCAL about information.
+
+    Parameters
+    ----------
+    parent : MainWindowView
+        An instance of MainWindowView
+    """
+
     def __init__(self, parent=None):
         super().__init__(parent)
-        # Define internal variables
 
         # Define main window
         self.setWindowTitle("About RasCAL 2")
@@ -62,10 +69,8 @@ def __init__(self, parent=None):
         main_layout.addStretch(1)
         self.setLayout(main_layout)
 
-    def update_rascal_info(self, parent):
-        """Obtain info about RASCAL (version, main settings etc.)
-        retrieved from general class information
-        """
+    def update_rascal_info(self):
+        """Obtain info about RASCAL (version, main settings etc.)."""
         matlab_path = MatlabHelper().get_matlab_path()
         if not matlab_path:
             matlab_path = "None"

rascal2/dialogs/settings_dialog.py

@@ -11,15 +11,15 @@
 
 
 class SettingsDialog(QtWidgets.QDialog):
-    def __init__(self, parent):
-        """
-        Dialog to adjust RasCAL-2 settings.
+    """Dialog to adjust RasCAL-2 settings.
 
-        Parameters
-        ----------
-        parent : MainWindowView
-            The view of the RasCAL-2 GUI
-        """
+    Parameters
+    ----------
+    parent : MainWindowView
+        The view of the RasCAL-2 GUI
+    """
+
+    def __init__(self, parent):
         super().__init__(parent)
 
         self.setModal(True)
@@ -59,32 +59,33 @@ def __init__(self, parent):
         self.setWindowTitle("Settings")
 
     def update_settings(self) -> None:
-        """Accept the changed settings"""
+        """Accept the changed settings."""
         self.parent().settings = self.settings
         if self.parent().presenter.model.save_path:
             self.parent().settings.save(self.parent().presenter.model.save_path)
         self.matlab_tab.set_matlab_paths()
         self.accept()
 
     def reset_default_settings(self) -> None:
-        """Reset the settings to the global defaults"""
+        """Reset the settings to the global defaults."""
         delete_local_settings(self.parent().presenter.model.save_path)
         self.parent().settings = Settings()
         self.accept()
 
 
 class SettingsTab(QtWidgets.QWidget):
-    def __init__(self, parent: SettingsDialog, group: SettingsGroups):
-        """A tab in the Settings Dialog tab layout.
+    """A tab in the Settings Dialog tab layout.
 
-        Parameters
-        ----------
-        parent : SettingsDialog
-            The dialog in which this tab lies
-        group : SettingsGroups
-            The set of settings with this value in "title" field of the
-            Settings object's "field_info" will be included in this tab.
-        """
+    Parameters
+    ----------
+    parent : SettingsDialog
+        The dialog in which this tab lies
+    group : SettingsGroups
+        The set of settings with this value in "title" field of the
+        Settings object's "field_info" will be included in this tab.
+    """
+
+    def __init__(self, parent: SettingsDialog, group: SettingsGroups):
         super().__init__(parent)
 
         self.settings = parent.settings
@@ -124,8 +125,9 @@ def modify_setting(self, setting: str):
 
 
 class MatlabSetupTab(QtWidgets.QWidget):
+    """Dialog to adjust Matlab location settings."""
+
     def __init__(self):
-        """Dialog to adjust Matlab location settings."""
         super().__init__()
 
         form_layout = QtWidgets.QGridLayout()
@@ -171,7 +173,7 @@ def open_folder_selector(self) -> None:
             self.changed = True
 
     def set_matlab_paths(self):
-        """Update MATLAB paths in arch file"""
+        """Update MATLAB paths in arch file."""
         if not self.changed:
             return
 

rascal2/dialogs/startup_dialog.py

@@ -27,13 +27,12 @@ class StartupDialog(QtWidgets.QDialog):
     folder_selector = QtWidgets.QFileDialog.getExistingDirectory
 
     def __init__(self, parent):
-        """
-        Initialize dialog.
+        """Initialize dialog.
 
         Parameters
         ----------
         parent: MainWindowView
-                An instance of the MainWindowView
+            An instance of the MainWindowView
         """
         super().__init__(parent)
 
@@ -67,7 +66,7 @@ def compose_layout(self):
         self.setLayout(main_layout)
 
     def create_loading_bar(self):
-        """Creates non-deterministic progress bar"""
+        """Creates non-deterministic progress bar."""
         self.loading_bar = QtWidgets.QProgressBar()
         self.loading_bar.setMinimum(0)
         self.loading_bar.setMaximum(0)
@@ -245,7 +244,7 @@ def create_project(self) -> None:
 
 
 class DisplayWidget(QtWidgets.QWidget):
-    """Fancy display widget for title and description items in a list"""
+    """Fancy display widget for title and description items in a list."""
 
     def __init__(self, title, desc):
         super().__init__()
@@ -280,7 +279,7 @@ def compose_layout(self):
         self.setLayout(main_layout)
 
     def create_load_tab(self):
-        """Creates the load project widget"""
+        """Creates the load project widget."""
         layout = QtWidgets.QVBoxLayout()
         layout.setSpacing(20)
 
@@ -304,7 +303,7 @@ def create_load_tab(self):
         self.tabs.addTab(load_tab, "Load Project")
 
     def create_list_widget_tab(self, tab_name: str):
-        """Create the list widget and add it to tab with given name
+        """Create the list widget and add it to tab with given name.
 
         Parameters
         ----------
@@ -328,7 +327,7 @@ def create_list_widget_tab(self, tab_name: str):
         return list_widget
 
     def create_example_tab(self):
-        """Creates the example widget"""
+        """Creates the example widget."""
         self.example_list_widget = self.create_list_widget_tab("Examples")
 
         for name, desc in EXAMPLES.items():
@@ -341,7 +340,7 @@ def create_example_tab(self):
             item.setSizeHint(item_widget.sizeHint())
 
     def create_recent_tab(self):
-        """Creates the recent project widget"""
+        """Creates the recent project widget."""
         recent_projects = update_recent_projects()
         recent_projects = recent_projects[:6]
         self.recent_list_widget = self.create_list_widget_tab("Recent Projects")
@@ -396,7 +395,7 @@ def load_project(self, item=None):
         self.block_for_worker(True)
 
     def block_for_worker(self, disabled: bool):
-        """Disable UI while worker is completing
+        """Disable UI while worker is completing.
 
         Parameters
         ----------

rascal2/main.py

@@ -10,7 +10,7 @@
 
 
 def ui_execute():
-    """Creates main window and executes GUI event loop
+    """Creates main window and executes GUI event loop.
 
     Returns
     -------
@@ -39,6 +39,7 @@ def ui_execute():
 
 
 def main():
+    """Entry point function for starting RasCAL."""
     multiprocessing.freeze_support()
     multiprocessing.set_start_method("spawn", force=True)
     sys.excepthook = log_uncaught_exceptions

rascal2/settings.py

@@ -41,7 +41,7 @@ def delete_local_settings(path: str | PathLike) -> None:
 
 
 class SettingsGroups(StrEnum):
-    """The groups of the RasCAL-2 settings, used to set tabs in the dialog"""
+    """The groups of the RasCAL-2 settings, used to set tabs in the dialog."""
 
     General = "General"
     Logging = "Logging"