Doc/rewrite (and code changes inspired by trying to document it)

.github/workflows/docs.yml

@@ -8,7 +8,7 @@ env:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - name: Install Python dependencies

.github/workflows/testing.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
       fail-fast: false
     steps:
 

docs/source/api.rst

@@ -1,86 +1,175 @@
-mpl gui
-=======
+mpl gui API Reference
+=====================
+
+.. automodule:: mpl_gui
+   :no-undoc-members:
 
-.. module:: mpl_gui
 
-Show
-----
 
+Select the backend
+------------------
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
 
-   mpl_gui.show
+
+   mpl_gui.select_gui_toolkit
 
 
 Interactivity
 -------------
 
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.ion
    mpl_gui.ioff
    mpl_gui.is_interactive
 
 
-Figure Fabrication
-------------------
+Unmanaged Figures
+-----------------
 
-Un-managed
-++++++++++
+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.figure
    mpl_gui.subplots
    mpl_gui.subplot_mosaic
 
 
+
+Display
++++++++
+
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
 
-   mpl_gui.promote_figure
 
-Managed
-+++++++
+
+   mpl_gui.display
+   mpl_gui.demote_figure
+
+
+
+Locally Managed Figures
+-----------------------
 
 
 .. autoclass:: mpl_gui.FigureRegistry
    :no-undoc-members:
    :show-inheritance:
 
 
+.. autoclass::    mpl_gui.FigureContext
+   :no-undoc-members:
+   :show-inheritance:
+
+Create Figures and Axes
++++++++++++++++++++++++
+
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
+
 
    mpl_gui.FigureRegistry.figure
    mpl_gui.FigureRegistry.subplots
    mpl_gui.FigureRegistry.subplot_mosaic
+
+
+Access managed figures
+++++++++++++++++++++++
+
+.. autosummary::
+   :toctree: _as_gen
+
+
    mpl_gui.FigureRegistry.by_label
+   mpl_gui.FigureRegistry.by_number
+   mpl_gui.FigureRegistry.figures
+
+
+
+Show and close managed Figures
+++++++++++++++++++++++++++++++
+
+
+.. autosummary::
+   :toctree: _as_gen
+
+
    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.global_figures
    :no-undoc-members:
-   :show-inheritance:
 
 
 
+Create Figures and Axes
++++++++++++++++++++++++
 
+.. autosummary::
+   :toctree: _as_gen
+
+
+   mpl_gui.global_figures.figure
+   mpl_gui.global_figures.subplots
+   mpl_gui.global_figures.subplot_mosaic
+
+
+Access managed figures
+++++++++++++++++++++++
 
 
-Select the backend
-------------------
 .. autosummary::
    :toctree: _as_gen
-   :nosignatures:
 
-   mpl_gui.select_gui_toolkit
+
+   mpl_gui.global_figures.by_label
+
+
+Show and close managed Figures
+++++++++++++++++++++++++++++++
+
+
+.. autosummary::
+   :toctree: _as_gen
+
+
+
+
+   mpl_gui.global_figures.show
+   mpl_gui.global_figures.show_all
+   mpl_gui.global_figures.close_all
+   mpl_gui.global_figures.close
+
+
+Interactivity
++++++++++++++
+
+.. autosummary::
+   :toctree: _as_gen
+
+
+
+   mpl_gui.global_figures.ion
+   mpl_gui.global_figures.ioff
+   mpl_gui.global_figures.is_interactive

docs/source/conf.py

@@ -129,6 +129,9 @@
     # and CI builds https://github.com/pydata/pydata-sphinx-theme/pull/386
     "collapse_navigation": not is_release_build,
     "show_prev_next": False,
+    "navigation_with_keys": False,
+    # "secondary_sidebar_items": "page-toc.html",
+    "footer_start": ["copyright", "sphinx-version", "doc_version"],
 }
 include_analytics = is_release_build
 if include_analytics:
@@ -153,9 +156,6 @@
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
-    "**": [
-        "relations.html",  # needs 'show_related': True theme option to display
-    ]
 }