docs: fix missing images in docs, update docs deps (#656)

* fix docs

* bump napari

docs/examples/demo_widgets/directory_dialog.py

@@ -0,0 +1,20 @@
+"""# Directory dialog widget
+
+A dialog to select a directory.
+"""
+
+from pathlib import Path
+
+from magicgui import magicgui
+
+
+# Select a directory, instead of file(s)
+@magicgui(directory={"mode": "d", "label": "Choose a directory"})
+def directorypicker(directory=Path("~")):
+    """Take a directory name and do something with it."""
+    print("The directory name is:", directory)
+    return directory
+
+
+directorypicker.directory.changed.connect(print)
+directorypicker.show(run=True)

docs/examples/demo_widgets/file_dialog.py

@@ -1,44 +1,20 @@
 """# File dialog widget
 
-A file dialog widget example.
+A dialog to select a file.
 """
 
 from pathlib import Path
-from typing import Sequence
 
-from magicgui import magicgui, use_app
+from magicgui import magicgui
 
 
 @magicgui(filename={"mode": "r"})
-def filepicker(filename=Path("~")):
+def filepicker(filename=Path("~")) -> Path:
     """Take a filename and do something with it."""
     print("The filename is:", filename)
     return filename
 
 
-# Sequence of paths
-# We change the label using "label" for added clarity
-# the filter argument restricts file types
-@magicgui(filenames={"label": "Choose Tiff files:", "filter": "*.tif"})
-def filespicker(filenames: Sequence[Path]):
-    """Take a filename and do something with it."""
-    print("The filenames are:", filenames)
-    return filenames
-
-
-# Select a directory, instead of file(s)
-@magicgui(directory={"mode": "d", "label": "Choose a directory"})
-def directorypicker(directory=Path("~")):
-    """Take a directory name and do something with it."""
-    print("The directory name is:", directory)
-    return directory
 
-
-filepicker.show()
-filespicker.show()
-directorypicker.show()
 filepicker.filename.changed.connect(print)
-filespicker.filenames.changed.connect(print)
-directorypicker.directory.changed.connect(print)
-
-use_app().run()
+filepicker.show(run=True)

docs/examples/demo_widgets/files_dialog.py

@@ -0,0 +1,23 @@
+"""# File dialog widget
+
+A dialog to select multiple files.
+"""
+
+from pathlib import Path
+from typing import Sequence
+
+from magicgui import magicgui
+
+
+# Sequence of paths
+# We change the label using "label" for added clarity
+# the filter argument restricts file types
+@magicgui(filenames={"label": "Choose Tiff files:", "filter": "*.tif"})
+def filespicker(filenames: Sequence[Path]) -> Sequence[Path]:
+    """Take a filename and do something with it."""
+    print("The filenames are:", filenames)
+    return filenames
+
+
+filespicker.filenames.changed.connect(print)
+filespicker.show(run=True)

docs/scripts/_gen_widgets.py

@@ -23,6 +23,9 @@
 
 ::: magicgui.widgets.{name}
     handler: widget_handler
+    options:
+        docstring_options:
+            warn_unknown_params: false
 """
 
 

docs/scripts/_hooks.py

@@ -13,7 +13,7 @@
 from importlib.machinery import ModuleSpec
 from itertools import count
 from textwrap import dedent
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Mapping
 
 from griffe.dataclasses import Alias
 from griffe.docstrings import numpy
@@ -30,29 +30,43 @@
 # TODO: figure out how to do this with options
 @contextmanager
 def _hide_numpy_warn():
+    if not hasattr(numpy, "_warn"):
+        yield
+        return
     before, numpy._warn = numpy._warn, lambda *x, **k: None
     yield
     numpy._warn = before
 
 
 def inject_dynamic_docstring(item: Alias, identifier: str) -> None:
-    module, name = identifier.rsplit(".", 1)
-    obj = getattr(import_module(module), name)
-    first_line, *rest = (obj.__doc__ or "").splitlines()
-    if first_line and item.target.docstring:
-        item.target.docstring.value = first_line + "\n" + dedent("\n".join(rest))
+    for i in range(1, 3):
+        module_name, *names = identifier.rsplit(".", 1)
+        try:
+            module = import_module(module_name)
+        except ModuleNotFoundError:
+            continue
+        else:
+            obj = module
+            for name in names:
+                obj = getattr(obj, name)
+            first_line, *rest = (obj.__doc__ or "").splitlines()
+            if first_line and item.target.docstring:
+                item.target.docstring.value = (
+                    first_line + "\n" + dedent("\n".join(rest))
+                )
+            break
 
 
 class WidgetHandler(PythonHandler):
-    def collect(self, identifier: str, config: dict) -> Any:
+    def collect(self, identifier: str, config: Mapping[str, Any]) -> Any:
         item = super().collect(identifier, config)
         if isinstance(item, Alias):
             inject_dynamic_docstring(item, identifier)
         # to edit default in the parameter table
         # item.parameters["something"].default = ...
         return item
 
-    def render(self, data: Any, config: dict) -> str:
+    def render(self, data: Any, config: Mapping[str, Any]) -> str:
         with _hide_numpy_warn():
             return super().render(data, config)
 
@@ -61,9 +75,26 @@ class MyLoader(importlib.abc.Loader):
     def create_module(self, spec):
         return types.ModuleType(spec.name)
 
-    def exec_module(self, module: types.ModuleType):
-        def get_handler(**kwargs):
-            return WidgetHandler(handler="python", **kwargs)
+    def exec_module(self, module: types.ModuleType) -> None:
+        def get_handler(
+            *,
+            theme: str,
+            custom_templates: str | None = None,
+            config_file_path: str | None = None,
+            paths: list[str] | None = None,
+            locale: str = "en",
+            load_external_modules: bool | None = None,
+            **config: Any,
+        ) -> PythonHandler:
+            return WidgetHandler(
+                handler="python",
+                theme=theme,
+                custom_templates=custom_templates,
+                config_file_path=config_file_path,
+                paths=paths,
+                locale=locale,
+                load_external_modules=load_external_modules,
+            )
 
         module.get_handler = get_handler
 

pyproject.toml

@@ -84,16 +84,16 @@ dev = [
 ]
 docs = [
     "mkdocs",
-    "mkdocs-material ~=9.4",
-    "mkdocstrings ==0.22.0",
-    "mkdocstrings-python ==1.6.2",
-    "mkdocs-gen-files",
-    "mkdocs-literate-nav",
+    "mkdocs-material ~=9.5",
+    "mkdocstrings ==0.25.1",
+    "mkdocstrings-python ==1.10.5",
+    "mkdocs-gen-files ==0.5.0",
+    "mkdocs-literate-nav ==0.6.1",
     "mkdocs-spellcheck[all]",
-    "mkdocs-gallery",
-    "qtgallery",
+    "mkdocs-gallery ==0.10.1",
+    "qtgallery ==0.0.2",
     # extras for all the widgets
-    "napari ==0.4.18",
+    "napari ==0.5.0",
     "pyqt6",
     "pint",
     "matplotlib",