Document custom themeable extension path

Author: iangow

plotnine/themes/theme.py

@@ -85,6 +85,9 @@ class theme:
 
         These simply bind together all the aspects of a themeable
         that can be themed. See [](`~plotnine.themes.themeable.themeable`).
+        Extension packages may provide additional themeables by defining
+        and importing subclasses of `themeable`, then passing values for
+        them as keyword arguments to `theme`.
 
     Notes
     -----

plotnine/themes/themeable.py

@@ -89,8 +89,11 @@ class axis_title(axis_title_x, axis_title_y):
 
     Notes
     -----
-    A user should never create instances of class
-    [](`~plotnine.themes.themeable.Themeable`) or subclasses of it.
+    Most users should not create instances of class
+    [](`~plotnine.themes.themeable.themeable`) or subclasses of it
+    directly. Extension authors may define subclasses; they are registered
+    by class name when their module is imported and can be used through
+    [](`~plotnine.themes.theme.theme`) keyword arguments.
     """
 
     def __init__(self, theme_element: element_base | str | float):

tests/test_theme.py

@@ -35,7 +35,8 @@
     theme_xkcd,
 )
 from plotnine.data import mtcars
-from plotnine.themes.themeable import panel_border
+from plotnine.coords.coord_cartesian import coord_cartesian
+from plotnine.themes.themeable import panel_border, themeable
 
 LT_MPL310 = version.parse(mpl.__version__) < version.parse("3.10")
 IS_CI = bool(os.environ.get("CI"))
@@ -124,6 +125,48 @@ def test_blank_panel_border_hides_polar_spine():
         plt.close(fig)
 
 
+def test_extension_themeable_applies_from_theme_kwargs():
+    class test_extension_panel_facecolor(themeable):
+        def apply_ax(self, ax):
+            super().apply_ax(ax)
+            ax.set_facecolor(self.properties["value"])
+
+    p = (
+        ggplot(mtcars, aes(x="wt", y="mpg"))
+        + geom_point()
+        + theme(test_extension_panel_facecolor="red")
+    )
+
+    fig = p.draw()
+    try:
+        assert fig.axes[0].get_facecolor() == (1.0, 0.0, 0.0, 1.0)
+    finally:
+        plt.close(fig)
+
+
+def test_coord_can_read_extension_themeable():
+    class test_extension_coord_title(themeable):
+        pass
+
+    class coord_reads_themeable(coord_cartesian):
+        def setup_ax(self, ax, panel_params, theme):
+            super().setup_ax(ax, panel_params, theme)
+            ax.set_title(theme.getp("test_extension_coord_title"))
+
+    p = (
+        ggplot(mtcars, aes(x="wt", y="mpg"))
+        + geom_point()
+        + coord_reads_themeable()
+        + theme(test_extension_coord_title="coord themeable")
+    )
+
+    fig = p.draw()
+    try:
+        assert fig.axes[0].get_title() == "coord themeable"
+    finally:
+        plt.close(fig)
+
+
 def test_element_line_dashed_capstyle():
     p = ggplot(mtcars, aes(x="wt", y="mpg")) + theme(
         panel_grid=element_line(