DOC: major re-write/re-organization of docs

Author: tacaswell

docs/source/api.rst

@@ -1,7 +1,19 @@
-mpl gui
-=======
+mpl gui API Reference
+=====================
+
+.. automodule:: mpl_gui
+   :no-undoc-members:
+
+
+
+Select the backend
+------------------
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
+   mpl_gui.select_gui_toolkit
 
-.. module:: mpl_gui
 
 Show
 ----
@@ -10,6 +22,7 @@ Show
    :toctree: _as_gen
    :nosignatures:
 
+
    mpl_gui.show
 
 
@@ -25,18 +38,21 @@ Interactivity
    mpl_gui.is_interactive
 
 
-Figure Fabrication
-------------------
+Locally Managed Figures
+-----------------------
 
 
-Managed
-+++++++
+.. autoclass:: mpl_gui.FigureRegistry
+   :no-undoc-members:
+   :show-inheritance:
 
 
-.. autoclass:: mpl_gui.FigureRegistry
+.. autoclass::    mpl_gui.FigureContext
    :no-undoc-members:
    :show-inheritance:
 
+Create Figures and Axes
++++++++++++++++++++++++
 
 .. autosummary::
    :toctree: _as_gen
@@ -45,24 +61,93 @@ Managed
    mpl_gui.FigureRegistry.figure
    mpl_gui.FigureRegistry.subplots
    mpl_gui.FigureRegistry.subplot_mosaic
+
+
+Access managed figures
+++++++++++++++++++++++
+
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
    mpl_gui.FigureRegistry.by_label
+   mpl_gui.FigureRegistry.by_number
+   mpl_gui.FigureRegistry.figures
+
+
+
+Show and close managed Figures
+++++++++++++++++++++++++++++++
+
+
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
    mpl_gui.FigureRegistry.show_all
    mpl_gui.FigureRegistry.close_all
+   mpl_gui.FigureRegistry.show
+   mpl_gui.FigureRegistry.close
 
 
-.. autoclass::    mpl_gui.FigureContext
+
+
+Globally managed
+----------------
+
+
+.. automodule:: mpl_gui.registry
    :no-undoc-members:
-   :show-inheritance:
 
 
 
+Create Figures and Axes
++++++++++++++++++++++++
 
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
+   mpl_gui.registry.figure
+   mpl_gui.registry.subplots
+   mpl_gui.registry.subplot_mosaic
+
+
+Access managed figures
+++++++++++++++++++++++
 
 
-Select the backend
-------------------
 .. autosummary::
    :toctree: _as_gen
    :nosignatures:
 
-   mpl_gui.select_gui_toolkit
+   mpl_gui.registry.by_label
+
+
+Show and close managed Figures
+++++++++++++++++++++++++++++++
+
+
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
+
+
+   mpl_gui.registry.show
+   mpl_gui.registry.show_all
+   mpl_gui.registry.close_all
+   mpl_gui.registry.close
+
+
+Interactivity
++++++++++++++
+
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
+
+   mpl_gui.registry.ion
+   mpl_gui.registry.ioff
+   mpl_gui.registry.is_interactive