wip

docs/_macros.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mkdocs_macros.plugin import MacrosPlugin
+
+EXAMPLES = Path(__file__).parent.parent / "examples"
+IMAGES = Path(__file__).parent / "images"
+
+
+def define_env(env: "MacrosPlugin"):
+    @env.macro
+    def insert_example(example: str, width: int = 300) -> list[Path]:
+        """Grab the top widgets of the application."""
+        if not example.endswith(".py"):
+            example += ".py"
+
+        src = (EXAMPLES / example).read_text()
+        output = f"```python\n{src}\n```\n\n"
+
+        dest = IMAGES / f"{example}.png"
+        if not (dest).exists():
+            src = src.replace("app.exec_()", "")
+            exec(src)
+            _grab(dest)
+
+        output += f"![Image title](../images/{dest.name}){{ loading=lazy; width={width} }}\n\n"
+        return output
+
+
+def _grab(dest: str | Path) -> list[Path]:
+    """Grab the top widgets of the application."""
+    from qtpy.QtWidgets import QApplication
+
+    w = next(iter(QApplication.topLevelWidgets()))
+    w.grab().save(str(dest))

docs/index.md

@@ -0,0 +1,2 @@
+# superqt documentation
+

docs/utilities/index.md

@@ -0,0 +1,7 @@
+# Utilities
+
+| Object                          | Description           |
+| -----------                     | --------------------- |
+| [`QMessageHandler`]()           | A context manager to intercept messages from Qt. |
+| [`@ensure_main_thread`]()        | Decorator that ensures a function is called in the main `QApplication` thread. |
+| [`@ensure_object_thread`]()      | Decorator that ensures a `QObject` method is called in the object's thread. |

docs/widgets/index.md

@@ -0,0 +1,31 @@
+# Widgets
+
+The following are QWidget subclasses:
+
+## Sliders and Numerical Inputs
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QDoubleSlider`]()             | Slider for float values |
+| [`QLabeledSlider`]()            | `QSlider` with editable `QSpinBox` that shows the current value |
+| [`QLabeledDoubleSlider`]()      | `QSlider` for float values with editable `QSpinBox` with the current value |
+| [`QRangeSlider`]()              | Multi-handle slider   |
+| [`QDoubleRangeSlider`]()        | Multi-handle slider for float values   |
+| [`QLabeledRangeSlider`]()       | `QRangeSlider` variant, with editable labels for each handle |
+| [`QLabeledDoubleRangeSlider`]() | `QDoubleRangeSlider` variant with editable labels for each handle |
+| [`QLargeIntSpinBox`]()          | `QSpinbox` that accepts arbitrarily large integers |
+
+## Labels and categorical inputs
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QSearchableListWidget`]()     | `QListWidget` variant with search field that filters available options |
+| [`QEnumComboBox`]()             | `QComboBox` that populates the combobox from a python `Enum` |
+| [`QSearchableComboBox`]()       | `QComboBox` variant that filters available options based on text input |
+| [`QElidingLabel`]()             | A `QLabel` variant that will elide text (add `…`) to fit width. |
+
+## Frames and containers
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QCollapsible`](./qcollapsible.md)              | A collapsible widget to hide and unhide child widgets. |

docs/widgets/qcollapsible.md

@@ -0,0 +1,3 @@
+# QCollapsible
+
+{{ insert_example('qcollapsible') }}

mkdocs.yml

@@ -0,0 +1,40 @@
+site_name: superqt
+site_url: https://github.com/napari/superqt
+site_description: >-
+  missing widgets and components for PyQt/PySide
+# Repository
+repo_name: napari/superqt
+repo_url: https://github.com/napari/superqt
+
+# Copyright
+copyright: Copyright © 2021 - 2022 Talley Lambert
+
+extra_css:
+  - stylesheets/extra.css
+
+watch: 
+  - src
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - search.highlight
+    - search.suggest
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - tables
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+
+plugins:
+  - search
+  # - autorefs
+  - macros:
+      module_name: docs/_macros