docs: add cmap and QSearchableTreeWidget to docs (#199)

docs/index.md

@@ -26,4 +26,4 @@ conda install -c conda-forge superqt
 
 ## Usage
 
-See the [Widgets](./widgets/) and [Utilities](./utilities/) pages for features offered by superqt.
+See the [Widgets](./widgets/index.md) and [Utilities](./utilities/index.md) pages for features offered by superqt.

docs/utilities/cmap.md

@@ -0,0 +1,12 @@
+# Colormap utilities
+
+See also:
+
+- [`superqt.QColormapComboBox`](../widgets/qcolormap.md)
+- [`superqt.cmap.CmapCatalogComboBox`](../widgets/colormap_catalog.md)
+
+::: superqt.cmap.draw_colormap
+
+::: superqt.cmap.QColormapLineEdit
+
+::: superqt.cmap.QColormapItemDelegate

docs/utilities/index.md

@@ -29,3 +29,4 @@
 | -----------                     | --------------------- |
 | [`QMessageHandler`](./qmessagehandler.md)           | A context manager to intercept messages from Qt. |
 | [`CodeSyntaxHighlight`](./code_syntax_highlight.md) | A `QSyntaxHighlighter` for code syntax highlighting. |
+| [`draw_colormap`](./cmap.md) | Function that draws a colormap into any QPaintDevice. |

docs/widgets/colormap_catalog.md

@@ -0,0 +1,35 @@
+# CmapCatalogComboBox
+
+Searchable `QComboBox` variant that contains the
+[entire cmap colormap catalog](https://cmap-docs.readthedocs.io/en/latest/catalog/)
+
+!!! note "requires cmap"
+
+    This widget uses the [cmap](https://cmap-docs.readthedocs.io/) library
+    to provide colormaps.  You can install it with:
+
+    ```shell
+    # use the `cmap` extra to include colormap support
+    pip install superqt[cmap]
+    ```
+
+You can limit the colormaps shown by setting the `categories` or
+`interpolation` keyword arguments.
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt.cmap import CmapCatalogComboBox
+
+app = QApplication([])
+
+catalog_combo = CmapCatalogComboBox(interpolation="linear")
+catalog_combo.setCurrentText("viridis")
+catalog_combo.show()
+
+app.exec()
+```
+
+{{ show_widget(130) }}
+
+{{ show_members('superqt.cmap.CmapCatalogComboBox') }}

docs/widgets/index.md

@@ -24,6 +24,9 @@ The following are QWidget subclasses:
 | [`QEnumComboBox`](./qenumcombobox.md)             | `QComboBox` that populates the combobox from a python `Enum` |
 | [`QSearchableComboBox`](./qsearchablecombobox.md)       | `QComboBox` variant that filters available options based on text input |
 | [`QSearchableListWidget`](./qsearchablelistwidget.md)     | `QListWidget` variant with search field that filters available options |
+| [`QSearchableTreeWidget`](./qsearchabletreewidget.md)     | `QTreeWidget` variant with search field that filters available options |
+| [`QColorComboBox`](./qcolorcombobox.md)            | `QComboBox` to select from a specified set of colors |
+| [`QColormapComboBox`](./qcolormap.md)            | `QComboBox` to select from a specified set of colormaps. |
 
 ## Frames and containers
 

docs/widgets/qcolorcombobox.md

@@ -0,0 +1,27 @@
+# QColorComboBox
+
+`QComboBox` designed to select from a specific set of colors.
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QColorComboBox
+
+app = QApplication([])
+
+colors = QColorComboBox()
+colors.addColors(['red', 'green', 'blue'])
+
+# show an "Add Color" item that opens a QColorDialog when clicked
+colors.setUserColorsAllowed(True)
+
+# emits a QColor when changed
+colors.currentColorChanged.connect(print)
+colors.show()
+
+app.exec_()
+```
+
+{{ show_widget(100) }}
+
+{{ show_members('superqt.QColorComboBox') }}

docs/widgets/qcolormap.md

@@ -0,0 +1,67 @@
+# QColormapComboBox
+
+`QComboBox` variant to select from a specific set of colormaps.
+
+!!! note "requires cmap"
+
+    This widget uses the [cmap](https://cmap-docs.readthedocs.io/) library
+    to provide colormaps.  You can install it with:
+
+    ```shell
+    # use the `cmap` extra to include colormap support
+    pip install superqt[cmap]
+    ```
+
+### ColorMapLike objects
+
+Colormaps may be specified in a variety of ways, such as by name (string), an iterable of a color/color-like objects, or as
+a [`cmap.Colormap`][] instance. See [cmap documentation for details on
+all ColormapLike types](https://cmap-docs.readthedocs.io/en/latest/colormaps/#colormaplike-objects)
+
+### Example
+
+```python
+from cmap import Colormap
+from qtpy.QtWidgets import QApplication
+
+from superqt import QColormapComboBox
+
+app = QApplication([])
+
+cmap_combo = QColormapComboBox()
+# see note above about colormap-like objects
+# as names from the cmap catalog
+cmap_combo.addColormaps(["viridis", "plasma", "magma", "gray"])
+# as a sequence of colors, linearly interpolated
+cmap_combo.addColormap(("#0f0", "slateblue", "#F3A003A0"))
+# as a `cmap.Colormap` instance with custom name:
+cmap_combo.addColormap(Colormap(("green", "white", "orange"), name="MyMap"))
+
+cmap_combo.show()
+app.exec()
+```
+
+{{ show_widget(200) }}
+
+### Style Customization
+
+Note that both the LineEdit and the dropdown can be styled to have the colormap
+on the left, or fill the entire width of the widget.
+
+To make the CombBox label colormap fill the entire width of the widget:
+
+```python
+from superqt.cmap import QColormapLineEdit
+cmap_combo.setLineEdit(QColormapLineEdit())
+```
+
+To make the CombBox dropdown colormaps fill
+less than the entire width of the widget:
+
+```python
+from superqt.cmap import QColormapItemDelegate
+delegate = QColormapItemDelegate(fractional_colormap_width=0.33)
+cmap_combo.setItemDelegate(delegate)
+```
+
+{{ show_members('superqt.QColormapComboBox') }}

docs/widgets/qsearchabletreewidget.md

@@ -0,0 +1,37 @@
+# QSearchableTreeWidget
+
+`QSearchableTreeWidget` combines a
+[`QTreeWidget`](https://doc.qt.io/qt-6/qtreewidget.html) and a `QLineEdit` for showing a mapping that can be searched by key.
+
+This is intended to be used with a read-only mapping and be conveniently created
+using `QSearchableTreeWidget.fromData(data)`. If the mapping changes, the
+easiest way to update this is by calling `setData`.
+
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QSearchableTreeWidget
+
+app = QApplication([])
+
+data = {
+    "none": None,
+    "str": "test",
+    "int": 42,
+    "list": [2, 3, 5],
+    "dict": {
+        "float": 0.5,
+        "tuple": (22, 99),
+        "bool": False,
+    },
+}
+tree = QSearchableTreeWidget.fromData(data)
+tree.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QSearchableTreeWidget') }}

mkdocs.yml

@@ -7,10 +7,7 @@ repo_name: pyapp-kit/superqt
 repo_url: https://github.com/pyapp-kit/superqt
 
 # Copyright
-copyright: Copyright © 2021 - 2022 Talley Lambert
+copyright: Copyright © 2021 - 2022
-
-extra_css:
-  - stylesheets/extra.css
 
 watch:
   - src
@@ -44,7 +41,6 @@ markdown_extensions:
 plugins:
   - search
   - autorefs
-  - mkdocstrings
   - macros:
       module_name: docs/_macros
   - mkdocstrings:
@@ -52,6 +48,7 @@ plugins:
         python:
           import:
             - https://docs.python.org/3/objects.inv
+            - https://cmap-docs.readthedocs.io/en/latest/objects.inv
           options:
               show_source: false
               docstring_style: numpy

pyproject.toml

@@ -59,7 +59,7 @@ dev = [
     "rich",
     "types-Pygments",
 ]
-docs = ["mkdocs-macros-plugin", "mkdocs-material", "mkdocstrings[python]"]
+docs = ["mkdocs-macros-plugin", "mkdocs-material", "mkdocstrings[python]", "pint", "cmap"]
 quantity = ["pint"]
 cmap = ["cmap >=0.1.1"]
 pyside2 = ["pyside2"]

src/superqt/cmap/_cmap_combo.py

@@ -78,7 +78,13 @@ class QColormapComboBox(QComboBox):
         return self._allow_user_colors
 
     def setUserAdditionsAllowed(self, allow: bool) -> None:
-        """Sets whether the user can add custom colors."""
+        """Sets whether the user can add custom colors.
+
+        If enabled, an "Add Colormap..." item will be added to the end of the
+        list. When clicked, a dialog will be shown to allow the user to select
+        a colormap from the
+        [cmap catalog](https://cmap-docs.readthedocs.io/en/latest/catalog/).
+        """
         self._allow_user_colors = bool(allow)
 
         idx = self.findData(self._add_color_text, Qt.ItemDataRole.DisplayRole)