updates to documentation for additional gallery

docs/conf.py

@@ -17,7 +17,7 @@
 sys.path.insert(0, str(Path(__file__).parent.resolve()))
 
 import matplotlib
-from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder
+# from sphinx_gallery
 
 import emcpy
 
@@ -38,39 +38,44 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'myst_parser',
+    # 'myst_parser',
     'sphinx.ext.githubpages',
     'sphinx_gallery.gen_gallery'
 ]
 
 
 # Sphinx gallery configuration
-subsection_order = ExplicitOrder([
-    '../examples/line_plots',
-    '../examples/scatter_plots',
-    '../examples/histograms',
-    '../examples/map_plots'
-])
+# gallery_order.py from the sphinxext folder provides the classes that
+# allow custom ordering of sections and subsections of the gallery
+from sphinxext.gallery_order import (
+    sectionorder as gallery_order_sectionorder,
+    subsectionorder as gallery_order_subsectionorder)
+
+# Create gallery dirs
+gallery_dirs = ["examples", "plot_types"]
+example_dirs = []
+for gd in gallery_dirs:
+    gd = gd.replace('gallery', 'examples')
+    example_dirs += [f'../galleries/{gd}']
 
 sphinx_gallery_conf = {
     'capture_repr': (),
     'filename_pattern': '^((?!skip_).)*$',
-    'examples_dirs': ['../examples'],   # path to example scripts
-    'gallery_dirs': ['gallery'],  # path to where to save gallery generated output
+    'examples_dirs': example_dirs,
+    'gallery_dirs': gallery_dirs,  # path to where to save gallery generated output
     'backreferences_dir': '../build/backrefs',
-    'subsection_order': subsection_order,
-    'within_subsection_order': ExampleTitleSortKey,
-    'matplotlib_animations': True,
+    'subsection_order': gallery_order_sectionorder,
+    'within_subsection_order': gallery_order_subsectionorder,
+    'matplotlib_animations': True
 }
 
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.ipynb']
 
 
 # -- Options for HTML output -------------------------------------------------

docs/getting_started/index.rst

@@ -10,7 +10,7 @@ The following links provide further documentation on the different branches with
 
     calculations.md
     io.md
-    plots.md
+#    galleries/plot_types/index
     statistics.md
     utilities.md
 

docs/index.rst

@@ -10,7 +10,7 @@ EMCPy
     :hidden:
 
     getting_started/index
-    gallery/index
+    galleries/examples/index
     installing
 
 

docs/sphinxext/gallery_order.py

@@ -0,0 +1,84 @@
+"""
+Configuration for the order of gallery sections and examples.
+Paths are relative to the conf.py file.
+"""
+
+from sphinx_gallery.sorting import ExplicitOrder
+
+# Gallery sections shall be displayed in the following order.
+# Non-matching sections are inserted at the unsorted position
+
+UNSORTED = "unsorted"
+
+# Sphinx gallery configuration
+examples_order = [
+    '../galleries/examples/line_plots',
+    '../galleries/examples/scatter_plots',
+    '../galleries/examples/histograms',
+    '../galleries/examples/map_plots',
+    UNSORTED
+]
+
+plot_types_order = [
+    '../galleries/plot_types/basic',
+    UNSORTED
+]
+
+folder_lists = [examples_order, plot_types_order]
+
+explicit_order_folders = [fd for folders in folder_lists
+                          for fd in folders[:folders.index(UNSORTED)]]
+explicit_order_folders.append(UNSORTED)
+explicit_order_folders.extend([fd for folders in folder_lists
+                               for fd in folders[folders.index(UNSORTED):]])
+
+class MplExplicitOrder(ExplicitOrder):
+    """For use within the 'subsection_order' key."""
+    def __call__(self, item):
+        """Return a string determining the sort order."""
+        if item in self.ordered_list:
+            return f"{self.ordered_list.index(item):04d}"
+        else:
+            return f"{self.ordered_list.index(UNSORTED):04d}{item}"
+
+# Subsection order:
+# Subsections are ordered by filename, unless they appear in the following
+# lists in which case the list order determines the order within the section.
+
+list_all = [
+    #  **Examples**
+    #  line
+    "line_plot", "line_plot_options", "multi_line_plot",
+    "inverted_log_scale", "SkewT"
+    #  scatter
+    "scatter", "scatter_with_regression_line",
+    "density_scatter"
+    # histograms
+    "histogram", "layered_histogram"
+    # map plots
+    "map_plot_no_data", "custom_map_domain", "map_scatter_2D",
+    "map_scatter", "map_gridded"
+
+    # **Plot Types**
+    # Basic
+    "line"
+    ]
+explicit_subsection_order = [item + ".py" for item in list_all]
+
+class MplExplicitSubOrder(ExplicitOrder):
+    """For use within the 'within_subsection_order' key."""
+    def __init__(self, src_dir):
+        self.src_dir = src_dir  # src_dir is unused here
+        self.ordered_list = explicit_subsection_order
+
+    def __call__(self, item):
+        """Return a string determining the sort order."""
+        if item in self.ordered_list:
+            return f"{self.ordered_list.index(item):04d}"
+        else:
+            # ensure not explicitly listed items come last.
+            return "zzz" + item
+
+# Provide the above classes for use in conf.py
+sectionorder = MplExplicitOrder(explicit_order_folders)
+subsectionorder = MplExplicitSubOrder

galleries/plot_types/README.txt

@@ -0,0 +1,20 @@
+## Plots
+
+The plotting section of EMCPy is the most mature and is used as the backend plotting for (eva)[https://github.com/JCSDA-internal/eva]. It uses declarative, object-oriented programming approach to handle complex plotting routines under the hood to simplify the experience for novice users while remaining robust so more experienced users can utilize higher-level applications.
+
+### Design
+The design was inspired by Unidata's (MetPy)[https://github.com/Unidata/MetPy] declarative plotting syntax. The structure is broken into three different levels: plot type level, plot level, figure level
+
+#### Plot Type Level
+This is the level where users will define their plot type objects and associated plot details. This includes adding the related data the user wants to plot and how the user wants to display the data i.e: color, line style, marker style, labels, etc.
+
+#### Plot Level
+This level is where users design how they want the overall subplot to look. Users can add multiple plot type objects and define titles, x and y labels, colorbars, legends, etc. 
+
+#### Figure Level
+This level where users defines high-level specifics about the actual figure itself. These include figure size, layout, defining information about subplot layouts like rows and columns, saving the figure, etc. 
+
+Plot Types
+----------
+
+Here is a collection of the current plot types that are currently available using EMCPy.

galleries/plot_types/basic/line.py

@@ -0,0 +1,46 @@
+"""
+Creating a simple line plot
+---------------------------
+
+Below is an example of how to plot a basic
+line plot using EMCPy's plotting method.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from emcpy.plots.plots import LinePlot
+from emcpy.plots.create_plots import CreatePlot, CreateFigure
+
+
+def main():
+
+    x = [1, 2, 3, 4, 5]
+    y = [1, 2, 3, 4, 5]
+
+    # Create line plot object
+    lp = LinePlot(x, y)
+    lp.label = 'line'
+
+    # Add line plot object to list
+    plt_list = [lp]
+
+    # Create plot object and add features
+    plot1 = CreatePlot()
+    plot1.plot_layers = [lp]
+    plot1.add_title('Test Line Plot')
+    plot1.add_xlabel('X Axis Label')
+    plot1.add_ylabel('Y Axis Label')
+    plot1.add_legend(loc='upper right')
+
+    # Create figure and save as png
+    fig = CreateFigure()
+    fig.plot_list = [plot1]
+    fig.create_figure()
+
+    plt.show()
+
+
+if __name__ == '__main__':
+    main()

src/emcpy/plots/create_plots.py

@@ -773,8 +773,8 @@ def _plot_legend(self, ax, legend):
         """
         leg = ax.legend(**legend)
 
-        for i, key in enumerate(leg.legendHandles):
-            leg.legendHandles[i]._sizes = [20]
+        for handle in leg.legend_handles:
+            handle._sizes = [20] 
 
     def _plot_text(self, ax, text_in):
         """