docs: Auto-generated examples gallery

.github/workflows/deploy_docs.yml

@@ -10,13 +10,17 @@ on:
 
 jobs:
   docs:
-    runs-on: macos-latest  # for the screenshots
+    runs-on: macos-latest # for the screenshots
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.x'
-      - run: pip install -e .[docs]
+          python-version: "3.x"
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[docs]
 
       - name: Deploy docs to GitHub Pages
         if: github.event_name == 'push'

.gitignore

@@ -121,6 +121,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+docs/generated*
 
 # mypy
 .mypy_cache/

docs/examples/README.md

@@ -0,0 +1,3 @@
+# Getting started
+
+A gallery of examples for magicgui.

docs/examples/applications/README.md

@@ -0,0 +1,3 @@
+# Demo applications
+
+Example applications built with magicgui.

examples/callable.py → docs/examples/applications/callable.py

@@ -1,20 +1,28 @@
+"""# Callable functions demo.
+
+This example demonstrates handling callable functions with magicgui.
+"""
 from magicgui import magicgui
 
 
 def f(x: int, y="a string") -> str:
+    """Example function F."""
     return f"{y} {x}"
 
 
 def g(x: int = 6, y="another string") -> str:
+    """Example function G."""
     return f"{y} asdfsdf {x}"
 
 
 @magicgui(call_button=True, func={"choices": ["f", "g"]})
 def example(func="f"):
+    """Ëxample function."""
     pass
 
 
 def update(f: str):
+    """Update function."""
     if len(example) > 2:
         del example[1]
     example.insert(1, magicgui(globals()[f]))

examples/chaining.py → docs/examples/applications/chaining.py

@@ -1,14 +1,20 @@
+"""# Chaining functions together.
+
+This example demonstrates chaining multiple functions together.
+"""
 from magicgui import magicgui, widgets
 
 
 @magicgui(auto_call=True)
 def func_a(x: int = 64, y: int = 64):
+    """Callable function A."""
     print("calling func_a")
     return x + y
 
 
 @magicgui(auto_call=True, input={"visible": False, "label": " ", "max": 100000})
 def func_b(input: int, mult=1.0):
+    """Callable function B."""
     print("calling func_b")
     result = input * mult
     # since these function defs live in globals(), you can update them directly
@@ -30,6 +36,7 @@ def _on_func_a(value: str):
     labels=False,
 )
 def func_c(input: int, format: str = "({} + {}) * {} is {}") -> str:
+    """Callable function C."""
     print("calling func_c\n")
     return format.format(func_a.x.value, func_a.y.value, func_b.mult.value, input)
 

examples/main_window.py → docs/examples/applications/hotdog.py

@@ -1,11 +1,15 @@
+"""# Hotdog or not app.
+
+Demo app to upload an image and classify if it's an hotdog or not.
+"""
 import pathlib
 from enum import Enum
 
 from magicgui import magicgui
 
 
 class HotdogOptions(Enum):
-    """All hotdog possibilities"""
+    """All hotdog possibilities."""
 
     Hotdog = 1
     NotHotdog = 0

docs/examples/applications/pint_quantity.py

@@ -0,0 +1,20 @@
+"""# Quantities with pint.
+
+Pint is a Python package to define, operate and manipulate physical quantities:
+the product of a numerical value and a unit of measurement.
+It allows arithmetic operations between them and conversions
+from and to different units.
+https://pint.readthedocs.io/en/stable/
+"""
+from pint import Quantity
+
+from magicgui import magicgui
+
+
+@magicgui
+def widget(q=Quantity("1 ms")):
+    """Widget allowing users to input quantity measurements."""
+    print(q)
+
+
+widget.show(run=True)

examples/snells_law.py → docs/examples/applications/snells_law.py

@@ -1,4 +1,7 @@
-"""Simple demonstration of magicgui."""
+"""# Snell's law demonstration using magicgui.
+
+Demo app for calculating angles of refraction according to Snell's law.
+"""
 
 import math
 from enum import Enum

docs/examples/applications/values_dialog.py

@@ -0,0 +1,21 @@
+"""# Input values dialog.
+
+A basic example of a user input dialog.
+
+This will pause code execution until the user responds.
+
+# ![Values input dialog](../../images/values_input.png){ width=50% }
+
+```python linenums="1"
+from magicgui.widgets import request_values
+
+vals = request_values(
+    age=int,
+    name={"annotation": str, "label": "Enter your name:"},
+    title="Hi, who are you?",
+)
+print(repr(vals))
+```
+"""
+
+# %%

examples/basic.py → docs/examples/basic_example.py

@@ -1,8 +1,13 @@
+"""# Basic example.
+
+A basic example using magicgui.
+"""
 from magicgui import magicgui
 
 
 @magicgui
 def example(x: int, y="hi"):
+    """Basic example function."""
     return x, y
 
 

examples/widget_demo.py → docs/examples/basic_widgets_demo.py

@@ -1,5 +1,10 @@
-"""Widget demonstration of magicgui."""
+"""# Basic widgets demo.
 
+Widget demonstration with magicgui.
+
+This code demonstrates a few of the widget types that magicgui can create
+based on the parameter types in your function.
+"""
 import datetime
 from enum import Enum
 from pathlib import Path

docs/examples/demo_widgets/README.md

@@ -0,0 +1,3 @@
+# Demo widget types
+
+Example gallery demonstrating the available widget types in magicgui.

examples/change_label.py → docs/examples/demo_widgets/change_label.py

@@ -1,9 +1,14 @@
+"""# Custom text labels for widgets.
+
+An example showing how to create custom text labels for your widgets.
+"""
 from magicgui import magicgui
 
 
 # use a different label than the default (the parameter name) in the UI
 @magicgui(x={"label": "widget to set x"})
 def example(x=1, y="hi"):
+    """Example function."""
     return x, y
 
 

examples/choices.py → docs/examples/demo_widgets/choices.py

@@ -1,4 +1,7 @@
-"""Choices for dropdowns can be provided in a few different ways."""
+"""# Dropdown selection widget.
+
+Choices for dropdowns can be provided in a few different ways.
+"""
 from enum import Enum
 
 from magicgui import magicgui, widgets
@@ -14,27 +17,32 @@ class Medium(Enum):
 
 @magicgui(ri={"choices": ["Oil", "Water", "Air"]}, auto_call=True)
 def as_list(ri="Water"):
+    """Function decorated with magicgui list of choices."""
     print("refractive index is", Medium[ri].value)
 
 
 @magicgui(auto_call=True)
 def as_enum(ri: Medium = Medium.Water):
+    """Function decorated with magicgui and enumeration."""
     print("refractive index is", ri.value)
 
 
 @magicgui(
     ri={"choices": [("Oil", 1.515), ("Water", 1.33), ("Air", 1.0)]}, auto_call=True
 )
 def as_2tuple(ri=1.33):
+    """Function decorated with magicgui tuple of choices."""
     print("refractive index is", ri)
 
 
 def get_choices(gui):
+    """Function returning tuple of material and refractive index value."""
     return [("Oil", 1.515), ("Water", 1.33), ("Air", 1.0)]
 
 
 @magicgui(ri={"choices": get_choices}, auto_call=True)
 def as_function(ri: float):
+    """Function to calculate refractive index."""
     print("refractive index is", ri)
 
 

examples/file_dialog.py → docs/examples/demo_widgets/file_dialog.py

@@ -1,4 +1,7 @@
-"""FileDialog with magicgui."""
+"""# File dialog widget.
+
+A file dialog widget example.
+"""
 from pathlib import Path
 from typing import Sequence
 

examples/image.py → docs/examples/demo_widgets/image.py

@@ -1,12 +1,15 @@
-"""Example of creating an Image Widget from a file.
+"""# Image widget.
+
+Example of creating an Image Widget from a file.
 
 (This requires pillow, or that magicgui was installed as ``magicgui[image]``)
 """
+
 from pathlib import Path
 
 from magicgui.widgets import Image
 
-img = Path(__file__).parent.parent / "tests" / "_test.jpg"
-image = Image(value=img)
+img = Path(__file__).parent.parent.parent / "images" / "_test.jpg"
+image = Image(value=str(img))
 image.scale_widget_to_image_size()
 image.show(run=True)

examples/log_slider.py → docs/examples/demo_widgets/log_slider.py

@@ -1,4 +1,7 @@
-"""Simple demonstration of magicgui."""
+"""# Log slider widget.
+
+A logarithmic scale range slider widget.
+"""
 from magicgui import magicgui
 
 
@@ -8,6 +11,7 @@
     input={"widget_type": "LogSlider", "max": 10000, "min": 1, "tracking": False},
 )
 def slider(input=1):
+    """Logarithmic scale slider."""
     return round(input, 4)
 
 

examples/login.py → docs/examples/demo_widgets/login.py

@@ -1,3 +1,7 @@
+"""# Password login.
+
+A password login field widget.
+"""
 from magicgui import magicgui
 
 
@@ -8,6 +12,7 @@
 # (unless you override "widget_type")
 @magicgui(password2={"widget_type": "Password"})
 def login(username: str, password: str, password2: str):
+    """User login credentials."""
     ...
 
 

examples/optional.py → docs/examples/demo_widgets/optional.py

@@ -1,3 +1,7 @@
+"""# Optional user choice.
+
+Optional user input using a dropdown selection widget.
+"""
 from typing import Optional
 
 from magicgui import magicgui
@@ -6,6 +10,7 @@
 # Using optional will add a '----' to the combobox, which returns "None"
 @magicgui(path={"choices": ["a", "b"]})
 def f(path: Optional[str] = None):
+    """Öptional user input function."""
     print(path, type(path))
 
 

examples/range_slider.py → docs/examples/demo_widgets/range_slider.py

@@ -1,10 +1,15 @@
+"""# Range slider widget.
+
+A double ended range slider widget.
+"""
 from typing import Tuple
 
 from magicgui import magicgui
 
 
 @magicgui(auto_call=True, range_value={"widget_type": "RangeSlider", "max": 500})
 def func(range_value: Tuple[int, int] = (20, 380)):
+    """Double ended range slider."""
     print(range_value)