DOC/API: put the top-level helpers back

Author: tacaswell

docs/source/api.rst

@@ -10,32 +10,54 @@ Select the backend
 ------------------
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.select_gui_toolkit
 
 
-Display
--------
+Interactivity
+-------------
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
 
 
-   mpl_gui.display
+   mpl_gui.ion
+   mpl_gui.ioff
+   mpl_gui.is_interactive
 
 
-Interactivity
--------------
+Unmanaged Figures
+-----------------
+
+Figure Creation
++++++++++++++++
+
+These are not strictly necessary as they are only thin wrappers around creating
+a `matplotlib.figure.Figure` instance and creating children in one line.
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
 
-   mpl_gui.ion
-   mpl_gui.ioff
-   mpl_gui.is_interactive
+
+
+   mpl_gui.figure
+   mpl_gui.subplots
+   mpl_gui.subplot_mosaic
+
+
+
+Display
++++++++
+
+.. autosummary::
+   :toctree: _as_gen
+
+
+
+   mpl_gui.display
+   mpl_gui.demote_figure
+
 
 
 Locally Managed Figures
@@ -56,7 +78,7 @@ Create Figures and Axes
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.FigureRegistry.figure
    mpl_gui.FigureRegistry.subplots
@@ -68,7 +90,7 @@ Access managed figures
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.FigureRegistry.by_label
    mpl_gui.FigureRegistry.by_number
@@ -82,7 +104,7 @@ Show and close managed Figures
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.FigureRegistry.show_all
    mpl_gui.FigureRegistry.close_all
@@ -106,7 +128,7 @@ Create Figures and Axes
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.global_figures.figure
    mpl_gui.global_figures.subplots
@@ -119,7 +141,7 @@ Access managed figures
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.global_figures.by_label
 
@@ -130,7 +152,7 @@ Show and close managed Figures
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
 
 
@@ -145,7 +167,7 @@ Interactivity
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
 
    mpl_gui.global_figures.ion

mpl_gui/__init__.py

@@ -29,11 +29,14 @@
 )
 from ._manage_backend import select_gui_toolkit as select_gui_toolkit  # noqa: F401
 from ._manage_backend import current_backend_module as _cbm
-from ._promotion import promote_figure as _promote_figure
+from ._promotion import (
+    promote_figure as _promote_figure,
+    demote_figure as demote_figure,
+)
 from ._creation import (
-    figure as _figure,
-    subplots as _subplots,
-    subplot_mosaic as _subplot_mosaic,
+    figure as figure,
+    subplots as subplots,
+    subplot_mosaic as subplot_mosaic,
 )
 
 
@@ -195,19 +198,19 @@ def by_number(self):
         self._ensure_all_figures_promoted()
         return {fig.canvas.manager.num: fig for fig in self.figures}
 
-    @functools.wraps(_figure)
+    @functools.wraps(figure)
     def figure(self, *args, **kwargs):
-        fig = _figure(*args, **kwargs)
+        fig = figure(*args, **kwargs)
         return self._register_fig(fig)
 
-    @functools.wraps(_subplots)
+    @functools.wraps(subplots)
     def subplots(self, *args, **kwargs):
-        fig, axs = _subplots(*args, **kwargs)
+        fig, axs = subplots(*args, **kwargs)
         return self._register_fig(fig), axs
 
-    @functools.wraps(_subplot_mosaic)
+    @functools.wraps(subplot_mosaic)
     def subplot_mosaic(self, *args, **kwargs):
-        fig, axd = _subplot_mosaic(*args, **kwargs)
+        fig, axd = subplot_mosaic(*args, **kwargs)
         return self._register_fig(fig), axd
 
     def _ensure_all_figures_promoted(self):