pymodaq_utils 5.3.6__tar.gz → 5.3.7__tar.gz

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymodaq_utils
-Version: 5.3.6
+Version: 5.3.7
 Summary: Modular Data Acquisition with Python
 Project-URL: Homepage, http://pymodaq.cnrs.fr
 Project-URL: Source, https://github.com/PyMoDAQ/PyMoDAQ

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/array_manipulation.py

@@ -379,7 +379,7 @@ def min_ind(x, axis=None):
 
 
 if __name__ == '__main__':                                          # pragma: no cover
-    from pymodaq.utils import daq_utils as utils
+    from pymodaq_utils import math_utils as utils
     import matplotlib.pyplot as plt
 
     x = random_step(00, 100, 5)

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/math_utils.py

@@ -14,6 +14,7 @@ logger = set_logger(get_module_name(__file__))
 
 
 def get_si_prefix(number) -> tuple[Number, str]:
+    """ Get the Scaled SI prefix of a Number """
     if number == 0:
         return 0, ""
 
@@ -33,7 +34,8 @@ def get_si_prefix(number) -> tuple[Number, str]:
     # Calculate the scaled number component
     scaled_value = number / (10 ** exponent)
     prefix_symbol = prefixes[exponent]
-
+    if prefix_symbol == '':
+        scaled_value = number
     return scaled_value, prefix_symbol
 
 

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/plugin_tools/checks.py

@@ -36,7 +36,7 @@ from pymodaq_utils.utils import get_entrypoints
 from pymodaq_utils.plugin_tools.contract import legacy_names
 from pymodaq_utils.plugin_tools import platforms
 from pymodaq_utils.plugin_tools.rules import (MANDATORY_MOVE_METHODS, MANDATORY_VIEWER_METHODS, PLACEHOLDER_NAMES_RE,
-                                              Finding, Severity, check_file_names, check_leftovers,
+                                              Finding, Severity, check_extensions, check_file_names, check_leftovers,
                                               check_os_classifiers, check_plugin_source, check_python_code,
                                               check_pyproject, colorize, is_valid_unit, package_root, project_root,
                                               use_color)
@@ -470,6 +470,7 @@ def check_package_sources(package: str, project: Optional[Path] = None) -> Check
     result.findings.extend(check_file_names(root))
     result.findings.extend(check_leftovers(package, root, project))
     result.findings.extend(check_python_code(root))
+    result.findings.extend(check_extensions(root))
     return result
 
 

pymodaq_utils-5.3.7/src/pymodaq_utils/plugin_tools/extension_checks.py

@@ -0,0 +1,102 @@
+"""Check the modules of Dashboard extensions: the ``check_extension`` command.
+
+It applies the rules PMQ330 to PMQ339 (see :func:`pymodaq_utils.plugin_tools.rules.check_extension_source`) to a python
+file or to a folder, whether the extension belongs to a plugin package or to PyMoDAQ itself. The sources are read,
+nothing is imported. ``check_plugin`` also applies these rules to the ``extensions`` folder of a plugin package.
+
+.. versionadded:: 5.3.7
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+from pymodaq_utils.plugin_tools.checks import FAIL_LEVELS, CheckResult, PluginReport
+from pymodaq_utils.plugin_tools.rules import check_extension_source, use_color
+
+
+def is_core_extension(path: Path) -> bool:
+    """Whether a file is in the ``extensions`` of the ``pymodaq`` package: the core extensions are registered in
+    ``pymodaq.extensions`` and do not need to define ``EXTENSION_NAME`` and ``CLASS_NAME``"""
+    parts = path.resolve().parts
+    return any(a == 'pymodaq' and b == 'extensions' for a, b in zip(parts, parts[1:]))
+
+
+def find_extension_files(target: Path) -> list[Path]:
+    """The python files to check: the file itself, or the modules of a folder
+
+    For a folder holding an ``extensions`` folder (the plugin package, or the repository with its ``src`` folder) the
+    modules of this folder are taken, otherwise all the modules of the folder and its sub-folders. The ``__init__``
+    and the private modules (starting with ``_``) are left out.
+    """
+    if target.is_file():
+        return [target]
+    folder = next((c for c in (target / 'extensions', *sorted(target.glob('src/*/extensions')),
+                               *sorted(target.glob('pymodaq_plugins_*/extensions'))) if c.is_dir()), target)
+    return [p for p in sorted(folder.rglob('*.py'))
+            if not p.name.startswith('_') and '__pycache__' not in p.parts]
+
+
+def check_extension_files(targets: Sequence[str | Path], fail_on: str = 'error',
+                          core: Optional[bool] = None) -> PluginReport:
+    """Run the extension rules on files or folders and return a report
+
+    Parameters
+    ----------
+    targets: list of str or Path
+        python files of extensions, or folders (see :func:`find_extension_files`)
+    fail_on: str
+        'error' (default), 'warning' or 'todo', see :data:`pymodaq_utils.plugin_tools.checks.FAIL_LEVELS`
+    core: bool
+        True for the extensions of PyMoDAQ: PMQ330 (``EXTENSION_NAME`` and ``CLASS_NAME`` missing) is then not
+        reported. By default found from the path of each file (``pymodaq/extensions``).
+    """
+    if fail_on not in FAIL_LEVELS:
+        raise ValueError(f'fail_on should be one of {list(FAIL_LEVELS)}')
+    results = []
+    for target in targets:
+        target = Path(target)
+        if not target.exists():
+            raise FileNotFoundError(target)
+        for path in find_extension_files(target):
+            is_core = is_core_extension(path) if core is None else core
+            findings = [f for f in check_extension_source(path) if not (is_core and f.code == 'PMQ330')]
+            try:
+                item = path.resolve().relative_to(Path.cwd()).as_posix()
+            except ValueError:
+                item = str(path)
+            results.append(CheckResult(item, findings=findings))
+    return PluginReport('extensions', results, fail_on)
+
+
+def main(argv=None) -> int:
+    """Print the report on extension modules: the ``check_extension`` command (or
+    ``python -m pymodaq_utils.plugin_tools.extension_checks``)
+
+    Returns 0 if the checks pass, 1 otherwise (so that it can also be used in a script or a CI).
+    """
+    import argparse
+    parser = argparse.ArgumentParser(prog='check_extension',
+                                     description='Check the modules of PyMoDAQ Dashboard extensions and print a report')
+    parser.add_argument('paths', nargs='+',
+                        help='python file of an extension, or folder: the extensions folder of a plugin package or of '
+                             'PyMoDAQ, or the plugin repository')
+    parser.add_argument('--fail-on', choices=list(FAIL_LEVELS), default='error',
+                        help="findings of this level and above give a non zero exit code ('todo': everything)")
+    parser.add_argument('--core', action='store_true', default=None,
+                        help='the extensions are part of PyMoDAQ: EXTENSION_NAME and CLASS_NAME are not required '
+                             '(found from the path by default)')
+    parser.add_argument('--color', choices=['auto', 'always', 'never'], default='auto',
+                        help='color the report: auto (default) if the output is a terminal and NO_COLOR is not set')
+    args = parser.parse_args(argv)
+    try:
+        report = check_extension_files(args.paths, args.fail_on, args.core)
+    except FileNotFoundError as e:
+        parser.error(f'{e} does not exist')
+    print(report.format(verbose=True, color=use_color(args.color)))
+    return 0 if report.ok else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/plugin_tools/platforms.py

@@ -214,6 +214,78 @@ def dynamic_classifiers(pyproject: dict, package_folder: Path) -> list[str]:
             classifiers_for(package_platforms(package_folder)))
 
 
+def _imported_files(path: Path, root: Path) -> set:
+    """Python files of the package imported by a module (absolute ``pymodaq_plugins_x.hardware.y`` or relative)"""
+    try:
+        tree = ast.parse(path.read_text(encoding='utf-8'))
+    except (SyntaxError, UnicodeDecodeError, OSError):
+        return set()
+    found = set()
+
+    def add(parts: list):
+        target = root.joinpath(*parts)
+        for candidate in (target.with_suffix('.py'), target / '__init__.py'):
+            if candidate.is_file():
+                found.add(candidate)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                parts = alias.name.split('.')
+                if parts[0] == root.name:
+                    add(parts[1:])
+        elif isinstance(node, ast.ImportFrom):
+            module = (node.module or '').split('.') if node.module else []
+            if node.level:
+                base = path.parent
+                for _ in range(node.level - 1):
+                    base = base.parent
+                try:
+                    parts = list(base.relative_to(root).parts) + module
+                except ValueError:
+                    continue
+            elif module[0] == root.name:
+                parts = module[1:]
+            else:
+                continue
+            add(parts)
+            for alias in node.names:
+                add(parts + [alias.name])
+    return found
+
+
+def windows_only_files(root: Path) -> set:
+    """Python files of a plugin package that only the Windows-only instruments use (directly or through the other
+    modules): code that only works on Windows is expected there. All of them if every instrument declares
+    ``supported_platforms = ('win32',)``. Files used by an instrument working elsewhere are never in it"""
+    files = [f for f in sorted(root.rglob('*.py')) if '__pycache__' not in f.parts]
+    if package_platforms(root) == {'win32'}:
+        return set(files)
+    graph = {f: _imported_files(f, root) for f in files}
+
+    def reachable(start: Path) -> set:
+        seen, todo = {start}, [start]
+        while todo:
+            for other in graph.get(todo.pop(), ()):
+                if other not in seen:
+                    seen.add(other)
+                    todo.append(other)
+        return seen
+
+    windows, others = set(), set()
+    for f in files:
+        if not (f.name.startswith('daq_move_') or re.match(r'daq_\w*viewer_', f.name)):
+            continue
+        try:
+            tree = ast.parse(f.read_text(encoding='utf-8'))
+        except (SyntaxError, UnicodeDecodeError, OSError):
+            continue
+        declared = [declared_in_class(c)[0] for c in tree.body
+                    if isinstance(c, ast.ClassDef) and PLUGIN_CLASS_RE.match(c.name)]
+        (windows if declared and all(d and set(d) == {'win32'} for d in declared) else others).update(reachable(f))
+    return windows - others
+
+
 def platforms_as_rst() -> str:
     """The accepted values as two reStructuredText tables, to be included in the documentation"""
     out = ['.. list-table::', '   :header-rows: 1', '   :widths: 20 20 60', '',

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/plugin_tools/rules.py

@@ -62,6 +62,20 @@ LEGACY_SETTINGS = {'multiaxes': 'controller', 'multi_status': 'controller_status
 WINDOWS_ONLY_IMPORTS = {'winreg', 'msvcrt', '_winreg', 'win32api', 'win32com'}
 WINDOWS_PATH_RE = re.compile(r'^[A-Za-z]:[\\/]')
 
+# modules of pymodaq that only remain as shims importing from their new location (with a deprecation warning)
+DEPRECATED_IMPORTS = {'pymodaq.extensions.custom_ext': 'pymodaq.utils.custom_ext',
+                      'pymodaq.extensions.h5browser': 'pymodaq_gui.h5modules.h5browser',
+                      'pymodaq.utils.math_utils': 'pymodaq_utils.math_utils',
+                      'pymodaq.utils.array_manipulation': 'pymodaq_utils.array_manipulation',
+                      'pymodaq.utils.parameter': 'pymodaq_gui.parameter',
+                      'pymodaq.utils.messenger': 'pymodaq_gui.messenger',
+                      'pymodaq.scripting': 'pymodaq_scripting'}
+# hooks of the extensions that were renamed (the base class still calls the old ones)
+DEPRECATED_EXTENSION_HOOKS = {'setup_docks': 'setup_docks_and_widgets', 'setup_menu': 'setup_menus_and_toolbars'}
+# managers that an extension gets from the Dashboard: it should not create its own
+# (its ModulesManager is the exception: the base class creates it for the extension)
+DASHBOARD_OWNED = ('ExperimentManager', 'StateManager')
+
 # features of [features] in pyproject.toml -> folders (relative to the package) holding the corresponding code
 FEATURE_FOLDERS = {'instruments': ('daq_move_plugins', 'daq_viewer_plugins'),
                    'extensions': ('extensions',),
@@ -237,11 +251,11 @@ def check_python_code(root: Path) -> list[Finding]:
     * PMQ315: invalid escape sequence in a string (``"C:\\Program Files"``): a warning of python since 3.6, a
       ``SyntaxWarning`` since 3.12, that will be an error
     * PMQ317: code that only works on Windows and is executed when the module is imported (``windll``, ``winreg``,
-      path with a drive letter): the plugin cannot be imported, nor listed, on the other systems. Not reported when
-      all the instruments of the package declare ``supported_platforms = ('win32',)``
+      path with a drive letter): the plugin cannot be imported, nor listed, on the other systems. Not reported in the
+      modules that only the instruments declaring ``supported_platforms = ('win32',)`` use
     """
     findings = []
-    windows_only_package = _platforms.package_platforms(root) == {'win32'}
+    windows_only = _platforms.windows_only_files(root)
     for path in _python_files(root):
         source = path.read_text(errors='replace')
         with warnings.catch_warnings(record=True) as caught:
@@ -270,7 +284,7 @@ def check_python_code(root: Path) -> list[Finding]:
                 what = f'the path {node.value!r}'
             if what is not None and not _guarded(node, parents):
                 windows.append((node.lineno, what))
-        if windows and not windows_only_package:
+        if windows and path not in windows_only:
             line, what = windows[0]
             more = f' (and {len(windows) - 1} more in this file)' if len(windows) > 1 else ''
             findings.append(Finding('PMQ317', Severity.WARNING, f'only works on Windows: {what}{more}',
@@ -640,6 +654,149 @@ def _check_controller_init(path: Path, tree: ast.Module) -> list[Finding]:
                     path, first.lineno)]
 
 
+# -------------------------------------------------------------------------------------------------------------------
+# PMQ33x: extensions (``extensions`` folder of a plugin package), from the source
+# -------------------------------------------------------------------------------------------------------------------
+
+EXTENSIONS_DOC = 'https://pymodaq.cnrs.fr/en/latest/developer_folder/extension_plugins.html'
+
+
+def _module_strings(tree: ast.Module) -> dict[str, ast.Assign]:
+    """The module level variables assigned a string, with their node"""
+    found = {}
+    for node in tree.body:
+        if (isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name)
+                and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)):
+            found[node.targets[0].id] = node
+    return found
+
+
+def _root_bases(cls: ast.ClassDef, classes: dict[str, ast.ClassDef], seen: Optional[set] = None) -> set[str]:
+    """Names of the bases of a class, following the bases defined in the same module"""
+    seen = seen or set()
+    names = set()
+    for base in _base_names(cls):
+        names.add(base)
+        if base in classes and base not in seen:
+            names |= _root_bases(classes[base], classes, seen | {cls.name})
+    return names
+
+
+def check_extension_source(path: Path) -> list[Finding]:
+    """Rules on a module of the ``extensions`` folder of a plugin package, without importing it
+
+    * PMQ330: ``EXTENSION_NAME`` or ``CLASS_NAME`` missing in a module defining an extension: the Dashboard does not
+      list it
+    * PMQ331: ``CLASS_NAME`` is not the name of a class of the module
+    * PMQ332: the class does not derive from ``CustomExt`` (``CustomApp`` has no access to the Dashboard)
+    * PMQ333: import from a module of pymodaq that only remains as a deprecated shim
+    * PMQ334: deprecated hooks ``setup_docks`` / ``setup_menu``
+    * PMQ335: the extension creates its own ExperimentManager or StateManager
+    * PMQ336: the ``__init__`` does not take the ``parent`` and ``dashboard`` arguments given by the Dashboard
+    * PMQ337: the ``__init__`` of a class deriving from ``CustomExt`` never calls ``self.setup_ui()``
+    * PMQ338: a class deriving directly from ``CustomExt`` has no ``_quit_fun`` guard, or one that never returns True
+    * PMQ339: the extension class overrides ``quit_fun`` instead of ``_quit_fun``
+    """
+    try:
+        tree = ast.parse(path.read_text(errors='replace'), filename=str(path))
+    except SyntaxError as e:
+        return [syntax_error_finding('PMQ300', path, e)]
+    findings = []
+    classes = {n.name: n for n in tree.body if isinstance(n, ast.ClassDef)}
+    strings = _module_strings(tree)
+    defines_ext = any('CustomExt' in _root_bases(c, classes) for c in classes.values())
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            modules = [node.module or ''] if isinstance(node, ast.ImportFrom) else [a.name for a in node.names]
+            for module in modules:
+                old = next((o for o in DEPRECATED_IMPORTS if module == o or module.startswith(o + '.')), None)
+                if old is not None:
+                    findings.append(Finding('PMQ333', Severity.WARNING, f"'{module}' is deprecated",
+                                            f"import from {DEPRECATED_IMPORTS[old]} instead", path, node.lineno))
+
+    if not (defines_ext or 'EXTENSION_NAME' in strings or 'CLASS_NAME' in strings):
+        return findings  # a helper module of the extensions folder, nothing else to check
+
+    missing = [name for name in ('EXTENSION_NAME', 'CLASS_NAME') if name not in strings]
+    if missing:
+        findings.append(Finding('PMQ330', Severity.ERROR,
+                                f"{' and '.join(missing)} not defined: the Dashboard will not list this extension",
+                                "define them at the module level as strings: EXTENSION_NAME is the name displayed in "
+                                "the Dashboard, CLASS_NAME the name of the extension class", path, 1))
+    class_name = strings['CLASS_NAME'].value.value if 'CLASS_NAME' in strings else None
+    imported = {a.asname or a.name.split('.')[0] for n in tree.body if isinstance(n, (ast.Import, ast.ImportFrom))
+                for a in n.names}
+    cls = classes.get(class_name) if class_name else None
+    if class_name and cls is None and class_name not in imported:
+        findings.append(Finding('PMQ331', Severity.ERROR, f"CLASS_NAME = '{class_name}' but there is no such class "
+                                f"in the module", 'CLASS_NAME should be the name of the extension class, the Dashboard '
+                                'gets the class from it', path, strings['CLASS_NAME'].lineno))
+    if cls is not None:
+        bases = _root_bases(cls, classes)
+        if 'CustomExt' not in bases and ('CustomApp' in bases or not bases - {'object'}):
+            findings.append(Finding('PMQ332', Severity.WARNING, f'{cls.name} does not derive from CustomExt',
+                                    "an extension is a CustomExt (from pymodaq.utils.custom_ext) to get the "
+                                    "Dashboard, not a CustomApp", path, cls.lineno))
+        methods = {n.name: n for n in cls.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+        for old, new in DEPRECATED_EXTENSION_HOOKS.items():
+            if old in methods:
+                findings.append(Finding('PMQ334', Severity.WARNING, f'{old}() is deprecated',
+                                        f"rename it {new}()", path, methods[old].lineno))
+        init = methods.get('__init__')
+        if init is not None:
+            args = init.args
+            if len(args.posonlyargs) + len(args.args) < 3 and args.vararg is None:
+                findings.append(Finding('PMQ336', Severity.ERROR, '__init__ should take (self, parent, dashboard)',
+                                        'the Dashboard creates the extension with the dock area and itself: '
+                                        'def __init__(self, parent, dashboard) then super().__init__(parent, dashboard)',
+                                        path, init.lineno))
+            if 'CustomExt' in _base_names(cls) and not any(
+                    isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and n.func.attr == 'setup_ui'
+                    for n in ast.walk(init)):
+                findings.append(Finding('PMQ337', Severity.WARNING, '__init__ never calls self.setup_ui()',
+                                        'without it no dock, menu or toolbar is created: call self.setup_ui() at the '
+                                        'end of __init__', path, init.lineno))
+        if 'CustomExt' in _root_bases(cls, classes) and 'quit_fun' in methods:
+            findings.append(Finding('PMQ339', Severity.ERROR, f'{cls.name} overrides quit_fun()',
+                                    'quit_fun of CustomExt calls _quit_fun (the guard) then closes the window and '
+                                    'shows the Dashboard again: override _quit_fun instead, so that these are kept',
+                                    path, methods['quit_fun'].lineno))
+        if 'CustomExt' in _base_names(cls) and 'quit_fun' not in methods:
+            quit_fun = methods.get('_quit_fun')
+            if quit_fun is None:
+                findings.append(Finding('PMQ338', Severity.WARNING, f'{cls.name} does not define _quit_fun()',
+                                        'quit_fun only closes the extension when _quit_fun() returns True, and the '
+                                        'one of CustomExt returns None: define _quit_fun as the guard that checks '
+                                        'that nothing is left running (threads, workers...), return False if '
+                                        'something is, True otherwise', path, cls.lineno))
+            elif not any(isinstance(n, ast.Return) and n.value is not None
+                         and not (isinstance(n.value, ast.Constant) and not n.value.value)
+                         for n in ast.walk(quit_fun)):
+                findings.append(Finding('PMQ338', Severity.WARNING, '_quit_fun() never returns True',
+                                        'quit_fun only closes the extension when _quit_fun() returns True: it is the '
+                                        'guard that returns False while something is left running (threads, workers'
+                                        '...) and True when everything is released', path, quit_fun.lineno))
+    in_main = {n for f in tree.body if isinstance(f, ast.FunctionDef) and f.name == 'main' for n in ast.walk(f)}
+    for node in ast.walk(tree):
+        if (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in DASHBOARD_OWNED
+                and node not in in_main):
+            findings.append(Finding('PMQ335', Severity.WARNING, f'{node.func.id}() created by the extension',
+                                    'use the ones of the Dashboard: self.experiment_manager and self.state_manager', path, node.lineno))
+    return findings
+
+
+def check_extensions(root: Path) -> list[Finding]:
+    """The rules on every module of the ``extensions`` folder of the package"""
+    folder = root / 'extensions'
+    findings = []
+    if folder.is_dir():
+        for path in _python_files(folder):
+            if not path.name.startswith('_'):
+                findings.extend(check_extension_source(path))
+    return findings
+
+
 def check_package_sources(package: str) -> list[Finding]:
     """All the static rules on an installed (or editable) plugin package: packaging, leftovers and plugin classes"""
     from pymodaq_utils.plugin_tools.checks import find_plugin_modules  # no import cycle at module level
@@ -652,6 +809,7 @@ def check_package_sources(package: str) -> list[Finding]:
     findings.extend(check_file_names(root))
     findings.extend(check_leftovers(package, root, project))
     findings.extend(check_python_code(root))
+    findings.extend(check_extensions(root))
     for mod in find_plugin_modules(package):
         file = Path(importlib.util.find_spec(mod.import_path).origin)
         findings.extend(check_plugin_source(file, mod.kind, mod.class_name))
@@ -684,3 +842,4 @@ def check_os_classifiers(package_folder: Path, project: Path) -> list[Finding]:
 check_plugin_source = _honour_noqa(check_plugin_source)
 check_python_code = _honour_noqa(check_python_code)
 check_leftovers = _honour_noqa(check_leftovers)
+check_extension_source = _honour_noqa(check_extension_source)

{pymodaq_utils-5.3.6 → pymodaq_utils-5.3.7}/src/pymodaq_utils/plugin_tools/scaffold.py

@@ -58,6 +58,8 @@ class $class_name(DAQ_Move_base):
       * the instrument (and models) this plugin was tested with
       * the drivers or libraries to install and where to find them
       * the specific attributes and parameters (see ``params``)
+
+    Documentation of the methods of a plugin: https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html
     """
     is_multiaxes = False  # TODO set to True if the controller drives several axes
     _axis_names = ['Axis1']  # TODO list (or dict name -> index) of the axes of the controller
@@ -92,6 +94,9 @@ class $class_name(DAQ_Move_base):
         ----------
         param: Parameter
             A given parameter (within settings) whose value has been changed by the user
+
+        See
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#hardware-settings
         """
         # TODO apply the changes on the controller, for instance:
         # if param.name() == 'a_parameter_you_added_in_params':
@@ -128,7 +133,11 @@ class $class_name(DAQ_Move_base):
         raise NotImplementedError  # TODO remove this line and close the communication with the controller
 
     def move_abs(self, value: DataActuator):
-        """Move the actuator to the absolute target defined by value"""
+        """Move the actuator to the absolute target defined by value
+
+        PyMoDAQ then waits for the target to be reached at ``epsilon``, see
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#value-reached
+        """
         value = self.check_bound(value)  # if the user checked the bounds, they are applied here
         self.target_value = value
         value = self.set_position_with_scaling(value)  # apply the scaling if the user specified one
@@ -137,7 +146,11 @@ class $class_name(DAQ_Move_base):
         self.emit_status(ThreadCommand('Update_Status', ['Some info you want to log']))
 
     def move_rel(self, value: DataActuator):
-        """Move the actuator to the relative target defined by value"""
+        """Move the actuator to the relative target defined by value
+
+        PyMoDAQ then waits for the target to be reached at ``epsilon``, see
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#value-reached
+        """
         value = self.check_bound(self.current_value + value) - self.current_value
         self.target_value = value + self.current_value
         value = self.set_position_relative_with_scaling(value)
@@ -146,10 +159,16 @@ class $class_name(DAQ_Move_base):
         self.emit_status(ThreadCommand('Update_Status', ['Some info you want to log']))
 
     def move_home(self):
-        """Call the reference method of the controller"""
+        """Call the reference method of the controller, so that the reference position becomes the home (zero)
+
+        PyMoDAQ does not poll the position after a move_home: call ``self.move_done()`` when the homing is finished,
+        see
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#moving-to-the-home-position
+        """
         raise NotImplementedError  # TODO remove this line and call the homing of the controller below
-        self.controller.home()
+        self.controller.home()  # blocking version. For an asynchronous one, give a callback calling self.move_done()
         self.emit_status(ThreadCommand('Update_Status', ['Some info you want to log']))
+        self.move_done()  # reads get_actuator_value() and signals the end of the move
 
     def stop_motion(self):
         """Stop the actuator and emit the move_done signal"""
@@ -186,6 +205,8 @@ class $class_name(DAQ_Viewer_base):
       * the instrument (and models) this plugin was tested with
       * the drivers or libraries to install and where to find them
       * the specific attributes and parameters (see ``params``)
+
+    Documentation of the methods of a plugin: https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html
     """
     params = comon_parameters + [
         # TODO add here, as dicts, the settings of your instrument
@@ -203,6 +224,9 @@ class $class_name(DAQ_Viewer_base):
         ----------
         param: Parameter
             A given parameter (within detector_settings) whose value has been changed by the user
+
+        See
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#hardware-settings
         """
         # TODO apply the changes on the controller, for instance:
         # if param.name() == 'a_parameter_you_added_in_params':
@@ -245,11 +269,17 @@ class $class_name(DAQ_Viewer_base):
     def grab_data(self, Naverage=1, **kwargs):
         """Start a grab from the detector
 
+        When the data are ready, emit them with dte_signal, see
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#emission-of-data
+        If they are not ready when this method returns, see
+        https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#data-ready
+
         Parameters
         ----------
         Naverage: int
             Number of hardware averaging (if the hardware can average, set hardware_averaging = True in the class
-            and implement it here)
+            and implement it here, see
+            https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html#hardware-averaging)
         kwargs: dict
             others optionals arguments
         """