display the colormaps in docs

cmweather/cm.py

@@ -143,3 +143,54 @@ def _generate_cmap(name, lutsize):
         mpl.colormaps.register(name=name, cmap=cmap, force=True)
     except AttributeError:
         mpl.cm.register_cmap(name=name, cmap=cmap)
+
+
+def _get_cmap_gallery_html(cmaps, sort_d=False):
+    """
+    return a html str representation of a colormap dictionary
+
+    use with either cmap_d from either .cm or .cm_colorblind,
+    reversed colormaps are excluded. The html repr of
+    individual colormaps is based on what the base
+    matplotlib.colors.Colormap._repr_html_() returns but
+    without the "over", "under" and "bad" labels.
+
+    Parameters
+    ----------
+    cmaps: dict
+        a dictionary of colormaps
+    sort_d: bool
+        if True (default False), will sort the cmaps by name
+
+    Returns
+    -------
+    str
+        the concatenated html str for the input colormap dict
+
+    """
+    import base64
+
+    def _get_cmap_div(cmap):
+        png_bytes = cmap._repr_png_()
+        png_base64 = base64.b64encode(png_bytes).decode('ascii')
+
+        return (
+            '<div style="vertical-align: middle;">'
+            f'<strong>{cmap.name}</strong> '
+            '</div>'
+            '<div class="cmap"><img '
+            f'alt="{cmap.name} colormap" '
+            f'title="{cmap.name}" '
+            'style="border: 1px solid #555;" '
+            f'src="data:image/png;base64,{png_base64}"></div>'
+        )
+
+    cm_names = [cnm for cnm in cmaps.keys() if not cnm.endswith('_r')]
+    if sort_d:
+        cm_names.sort()
+
+    html_str = ''
+    for cm_name in cm_names:
+        html_str += _get_cmap_div(cmaps[cm_name])
+
+    return html_str

docs/source/api.md

@@ -1,3 +1,12 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+
 # Reference
 
 ## Color Vision Deficiency Friendly Colormaps (`cmweather.cm_colorblind`)
@@ -9,6 +18,17 @@
     :show-inheritance:
 ```
 
+```{code-cell} ipython3
+:tags: [remove-input]
+
+from IPython.display import HTML
+from cmweather.cm_colorblind import cmap_d
+from cmweather.cm import _get_cmap_gallery_html
+
+html_str = _get_cmap_gallery_html(cmap_d, sort_d=False)
+display(HTML(html_str))
+```
+
 ## More Weather Colormaps (`cmweather.cm`)
 
 ```{eval-rst}
@@ -17,3 +37,13 @@
     :undoc-members:
     :show-inheritance:
 ```
+
+```{code-cell} ipython3
+:tags: [remove-input]
+
+from IPython.display import HTML
+from cmweather.cm import cmap_d, _get_cmap_gallery_html
+
+html_str = _get_cmap_gallery_html(cmap_d, sort_d=True)
+display(HTML(html_str))
+```

docs/source/index.md

@@ -9,8 +9,8 @@ caption: Getting Started
 hidden:
 ---
 usage
-contributing
 api
+contributing
 ```
 
 ## Feedback

tests/test_cm_html_repr.py

@@ -0,0 +1,13 @@
+import pytest
+
+from cmweather import cm, cm_colorblind
+
+
+@pytest.mark.parametrize('cmap_d,sort_d', [(cm.cmap_d, True), (cm_colorblind.cmap_d, False)])
+def test_get_cmap_gallery_html(cmap_d, sort_d):
+    html_str = cm._get_cmap_gallery_html(cmap_d, sort_d=sort_d)
+
+    assert isinstance(html_str, str)
+    assert len(html_str) > 0
+    assert html_str.startswith('<div')
+    assert html_str.endswith('</div>')