updated doc strings

pyproject.toml

@@ -77,15 +77,6 @@ dependencies = [
 
 
 [project.optional-dependencies]
-dev-docs = [
-    "Sphinx==7.2.6",
-    "numpydoc==1.6.0",
-    "sphinx-rtd-dark-mode==1.3.0",
-    "sphinx-rtd-theme==2.0.0",
-]
-
-dev-lint-format = ["ruff==0.2.1"]
-
 dev-test = ["pytest", "pytest-qt", "coverage"]
 
 [tool.setuptools.dynamic]

tests/conftest.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 """
-This file contains unit tests for all qudi fit routines for exponential decay models.
+This file contains the fixtures and functions that are commonly used across tests.
 
 Copyright (c) 2021, the qudi developers. See the AUTHORS.md file at the top-level directory of this
 distribution and on <https://github.com/Ulm-IQO/qudi-core/>
@@ -35,6 +35,7 @@
 
 @pytest.fixture(scope="module")
 def qt_app():
+    """ Fixture of QApplication instance to enable GUI """
     app_cls = QtWidgets.QApplication
     app = app_cls.instance()
     if app is None:
@@ -43,42 +44,52 @@ def qt_app():
 
 @pytest.fixture(scope="module")
 def qudi_instance():
+    """ Fixture for Qudi instace """
     instance = application.Qudi.instance()
     if instance is None:
         instance = application.Qudi(config_file=CONFIG)
     return instance
 
 @pytest.fixture(scope="module")
 def module_manager(qudi_instance):
+    """ Fixture for module manager """
     return qudi_instance.module_manager
 
 @pytest.fixture(scope='module')
 def config():
+    """ Fixture for loaded config """
     configuration = (yaml_load(CONFIG))
     return configuration
 
 @pytest.fixture(scope='module')
 def gui_modules(config):
+    """ Fixture for list of Gui modules from the config """
     base = 'gui'
     modules  = list(config[base].keys())
     return modules
 
 @pytest.fixture(scope='module')
 def logic_modules(config):
+    """ Fixture for list of logic modules from the config """
     base = 'logic'
     modules  = list(config[base].keys())
     return modules
 
 @pytest.fixture(scope='module')
 def hardware_modules(config):
+    """ Fixture for list of hardware modules from the config """
     base = 'hardware'
     modules  = list(config[base].keys())
     return modules
 
 def run_qudi(timeout=150000):
-    """
-    This function runs a qudi instance with a timer
-    """    
+    """    This function runs a qudi instance with a timer
+
+    Parameters
+    ----------
+    timeout : int, optional
+        timeout for the qudi session, by default 150000
+    """  
     app_cls = QtWidgets.QApplication
     app = app_cls.instance()
     if app is None:

tests/test.cfg

@@ -1,5 +1,5 @@
-#  Example Qudi configuration file.
-#  The recommended path for user specific files is C:\Users\<user_name>\qudi\config
+#  Test Qudi configuration file.
+#  This config doesn't have the task manager module unlike the default/dummy config as the module works a bit differently and breaks the tests
 
 global:
     # list of modules to load when starting

tests/test_OdmrLogic.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 """
-This file contains unit tests for all qudi fit routines for exponential decay models.
+This file contains unit tests for all Odmr logic module.
 
 Copyright (c) 2021, the qudi developers. See the AUTHORS.md file at the top-level directory of this
 distribution and on <https://github.com/Ulm-IQO/qudi-core/>
@@ -36,14 +36,39 @@
 
 
 def get_scanner(module):
+    """Getter for scanner module instance for logic module
+
+    Parameters
+    ----------
+    module : Object
+        logic module instance
+
+    Returns
+    -------
+    Object
+        Scanner module instance
+    """    
     return module._data_scanner()
 
 def get_microwave(module):
+    """Getter for microwave module instance for logic module
+
+    Parameters
+    ----------
+    module : Object
+        logic module instance
+
+    Returns
+    -------
+    Object
+        microwave module instance
+    """    
     return module._microwave()
 
 def get_odmr_range(length, scanner):
     """
     Simulate odmr scan data and return signal data
+
     Parameters
     ----------
     length : int
@@ -62,6 +87,20 @@ def get_odmr_range(length, scanner):
     return signal_data_range
 
 def get_tolerance(value, bound):
+    """Upper and lower boundaries for range check
+
+    Parameters
+    ----------
+    value : float
+        Input value
+    bound : str
+        lower or upper bound category
+
+    Returns
+    -------
+    int
+        the limit
+    """    
     return int(value + value * TOLERANCE/100) if bound == 'upper' else int(value - value * TOLERANCE/100)
 
 
@@ -85,6 +124,12 @@ def module(remote_instance):
 #@pytest.fixture(autouse=True)
 #Uncomment the above line to enable the coverage fixture
 def coverage_for_each_test(request):
+    """save coverage report
+
+    Parameters
+    ----------
+    request : request
+    """    
     cov = coverage.Coverage()
     cov.start()
     yield

tests/test_modify_status_var_sample.py → tests/test_modify_status_var_example.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 """
-This file contains unit tests for all qudi fit routines for exponential decay models.
+This test shows how a single status variable can be updated via file and tested through a remote connection
 
 Copyright (c) 2021, the qudi developers. See the AUTHORS.md file at the top-level directory of this
 distribution and on <https://github.com/Ulm-IQO/qudi-core/>
@@ -31,12 +31,36 @@
 VALUE = 10
 
 def get_status_var_file(instance):
+    """This function returns the path for status variable file 
+
+    Parameters
+    ----------
+    instance : Object
+        Instance of the logic module
+
+    Returns
+    -------
+    str
+        File path
+    """    
     file_path = get_module_app_data_path(
             instance.__class__.__name__, instance.module_base, instance.module_name
         )
     return file_path
 
 def load_status_var(file_path):    
+    """This function returns the loaded status variable from the file
+
+    Parameters
+    ----------
+    file_path : str
+        file path of status variable
+
+    Returns
+    -------
+    dict
+        dictionary of status variables
+    """    
     try:
         variables = yaml_load(file_path, ignore_missing=True)
     except Exception as e:
@@ -45,10 +69,35 @@ def load_status_var(file_path):
     return variables
 
 def modify_status_var(status_vars, var, value):
+    """Setting status variable
+
+    Parameters
+    ----------
+    status_vars : dict
+        status variable dict
+    var : str
+        the variable to be set from the status variable dict
+    value : Any
+        value to be set
+
+    Returns
+    -------
+    dict
+        status var
+    """    
     status_vars[var] = value
     return status_vars
 
 def dump_status_variables(vars, file_path):
+    """Dump updated status variable to yaml
+
+    Parameters
+    ----------
+    vars : dict
+        status variable dict
+    file_path : str
+        file path for status variable
+    """    
     try:
         yaml_dump(file_path, vars)
     except Exception as e:
@@ -67,6 +116,7 @@ def logic_instance(remote_instance):
 
 def test_status_vars(qudi_instance, qt_app):
     """ Modifying a specific saved status variable for a specific module
+
     Parameters
     ----------
     qudi_instance : fixture
@@ -90,6 +140,7 @@ def test_status_vars(qudi_instance, qt_app):
 
 def test_status_vars_changed(logic_instance, qudi_instance):
     """Test whether the status variable has changed
+    
     Parameters
     ----------
     logic_instance : fixture

tests/test_modify_status_var_file.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 """
-This file contains unit tests for all qudi fit routines for exponential decay models.
+This test modifies all status variables via file and then runs all the modules through a remote connection
 
 Copyright (c) 2021, the qudi developers. See the AUTHORS.md file at the top-level directory of this
 distribution and on <https://github.com/Ulm-IQO/qudi-core/>
@@ -30,9 +30,27 @@
 
 @pytest.fixture
 def module_manager(remote_instance):
+    """ Fixture for module manager of qudi remote instance """
     return remote_instance.module_manager
 
 def generate_random_value(var):
+    """Generate random values for a given data type
+
+    Parameters
+    ----------
+    var : Any
+        Initial value
+
+    Returns
+    -------
+    Any
+        Random value
+
+    Raises
+    ------
+    ValueError
+        when data type is not valid
+    """    
     if isinstance(var, int):
         return random.randint(-100, 100)
 
@@ -58,12 +76,36 @@ def generate_random_value(var):
         raise ValueError(f"Unsupported data type: {type(var)}")
 
 def get_status_var_file(instance):
+    """This function returns the path for status variable file 
+
+    Parameters
+    ----------
+    instance : Object
+        Instance of the logic module
+
+    Returns
+    -------
+    str
+        File path
+    """  
     file_path = get_module_app_data_path(
             instance.__class__.__name__, instance.module_base, instance.module_name
         )
     return file_path
 
-def load_status_var(file_path):    
+def load_status_var(file_path):   
+    """This function returns the loaded status variable from the file
+
+    Parameters
+    ----------
+    file_path : str
+        file path of status variable
+
+    Returns
+    -------
+    dict
+        dictionary of status variables
+    """   
     try:
         variables = yaml_load(file_path, ignore_missing=True)
     except Exception as e:
@@ -72,6 +114,18 @@ def load_status_var(file_path):
     return variables
 
 def modify_status_var(status_vars):
+    """This function updates the status variables with random values of the same data type
+
+    Parameters
+    ----------
+    status_vars : dict
+        All status vars of a module
+
+    Returns
+    -------
+    dict
+        updated status vars
+    """    
     for status_var in status_vars:
         status_var_value = status_vars[status_var]
         if not ( isinstance(status_var_value, float) or isinstance(status_var_value, int)):
@@ -82,6 +136,15 @@ def modify_status_var(status_vars):
     return status_vars
 
 def dump_status_variables(vars, file_path):
+    """Dump updated status variable to yaml
+
+    Parameters
+    ----------
+    vars : dict
+        status variable dict
+    file_path : str
+        file path for status variable
+    """    
     try:
         yaml_dump(file_path, vars)
     except Exception as e: