WIP

base_classes/NXdata.nxdl.xml

@@ -60,6 +60,8 @@
 			does not describe how the data is to be plotted or even the dimensionality of the plot.
 			https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute
 
+		.. include:: data/index.rst
+
 		**Usage:**
 
 		.. admonition:: Plot data versus x axis

dev_tools/apps/manual_app.py

@@ -6,6 +6,7 @@
 from ..globals import directories
 from ..nxdl import iter_definitions
 from ..nxdl import validate_definition
+from ..utils.copy import copy_directories
 from ..utils.copy import copy_files
 from ..utils.copy import copydir
 from ..utils.diff import diff_ascii
@@ -22,7 +23,7 @@ def manual_args(parser):
     parser.add_argument(
         "--prepare",
         action="store_true",
-        help="Create the build files for the NeXus Impatient Guide",
+        help="Create the build files for the NeXus documentation",
     )
     parser.add_argument(
         "--diff",
@@ -107,14 +108,25 @@ def manual_exec(args):
                     with open(index_file, "w") as fh:
                         fh.writelines(rst_lines)
 
-    # Generate the anchor list in several format
     if args.prepare:
+        directories.manual_build_root()
         print("generate anchor list files in", output_path)
         anchor_registry.write()
+
+        print("copy extra files", output_path)
         copy_files(EXTRA_FILES)
 
+        print("copy extra directories", output_path)
+        copy_directories(EXTRA_DIRECTORIES)
+
 
 # Path relative to source directory,
 # Path relative to build directory,
 # Overwrite (boolean)
-EXTRA_FILES = [["NXDL_VERSION", "NXDL_VERSION", True], ["LGPL.txt", "LGPL.txt", True]]
+EXTRA_FILES = [
+    ["NXDL_VERSION", "NXDL_VERSION", True],
+    ["LGPL.txt", "LGPL.txt", True],
+]
+EXTRA_DIRECTORIES = [
+    ["galleries", "galleries", True],
+]

dev_tools/utils/copy.py

@@ -28,3 +28,15 @@ def copy_files(files: List[Tuple[str, str, bool]]) -> None:
             copyfile(from_path, to_path)
         else:
             print("already exists", to_path)
+
+
+def copy_directories(dirs: List[Tuple[str, str, bool]]) -> None:
+    source_root = directories.get_source_root()
+    build_root = directories.get_build_root()
+    for from_subname, to_subname, overwrite in dirs:
+        to_path = build_root / to_subname
+        if overwrite or not to_path.exists():
+            from_path = source_root / from_subname
+            copydir(from_path, to_path)
+        else:
+            print("already exists", to_path)

galleries/nxdata/GALLERY_HEADER.rst

@@ -0,0 +1 @@
+**Usage**

galleries/nxdata/plot_curve1.py

@@ -0,0 +1,38 @@
+"""
+===============
+Curve (1D Grid)
+===============
+
+Curve (not necessarily evenly spaced)
+
+.. code::
+
+  @NX_class = "NXroot"
+  @default = "scan1"
+  scan1:NXentry
+    @NX_class = "NXentry"
+    @default = "data"
+    data:NXdata
+      @NX_class = "NXdata"
+      @auxiliary_signals = ["y2"]
+      @axes = ["x"]
+      @signal = "y1"
+      x:NX_INT64[10]
+      y1:NX_FLOAT64[10]
+      y2:NX_FLOAT64[10]
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+plt.style.use("_mpl-gallery")
+
+fig, ax = plt.subplots()
+
+x = np.arange(10) ** 2
+y1 = 4 + np.sin(2 * x)
+y2 = 2 + np.sin(3 * x)
+ax.plot(x, y1, "o-", label="y1")
+ax.plot(x, y2, "go-", label="y2")
+
+plt.show()

galleries/nxdata/plot_curve2.py

@@ -0,0 +1,66 @@
+"""
+===============
+Curve (1D Grid)
+===============
+
+Curve (not necessarily evenly spaced)
+
+.. code::
+
+  @NX_class = "NXroot"
+  @default = "scan1"
+  scan1:NXentry
+    @NX_class = "NXentry"
+    @default = "data"
+    data:NXdata
+      @NX_class = "NXdata"
+      @auxiliary_signals = ["y2"]
+      @axes = ["x"]
+      @signal = "y1"
+      x:NX_INT64[10]
+      y1:NX_FLOAT64[10]
+      y2:NX_FLOAT64[10]
+"""
+
+# %%
+# HDF5 example in Python.
+import h5py
+import numpy as np
+
+with h5py.File("curve.h5", "w") as root:
+    root.attrs["NX_class"] = "NXroot"
+    scan1 = root.create_group("scan1")
+    scan1.attrs["NX_class"] = "NXentry"
+    data = scan1.create_group("data")
+    data.attrs["NX_class"] = "NXdata"
+
+    data.attrs["axes"] = ["x"]
+    data.attrs["signal"] = "y1"
+    data.attrs["auxiliary_signals"] = ["y2"]
+    x = np.arange(10) ** 2
+    data["x"] = x
+    data["y1"] = 4 + np.sin(2 * x)
+    data["y2"] = 2 + np.sin(3 * x)
+
+# %%
+# Plot example in Python.
+import matplotlib.pyplot as plt
+
+plt.style.use("_mpl-gallery")
+
+fig, ax = plt.subplots()
+
+with h5py.File("curve.h5", "r") as root:
+    data = root["/scan1/data"]
+
+    xname = data.attrs["axes"][0]
+    yname1 = data.attrs["signal"]
+    yname2 = data.attrs["auxiliary_signals"][0]
+
+    x = data[xname][()]
+    y1 = data[yname1][()]
+    y2 = data[yname2][()]
+    ax.plot(x, y1, "o-", label=yname1)
+    ax.plot(x, y2, "go-", label=yname2)
+
+plt.show()

galleries/nxdata/plot_histogram_1d.py

@@ -0,0 +1,25 @@
+"""
+============
+1D Histogram
+============
+
+1D Histogram (not necessarily evenly spaced)
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+plt.style.use("_mpl-gallery")
+
+# make data:
+x = 0.5 + np.arange(8)
+y = [4.8, 5.5, 3.5, 4.6, 6.5, 6.6, 2.6, 3.0]
+
+# plot
+fig, ax = plt.subplots()
+
+ax.bar(x, y, width=1, edgecolor="white", linewidth=0.7)
+
+ax.set(xlim=(0, 8), xticks=np.arange(1, 8), ylim=(0, 8), yticks=np.arange(1, 8))
+
+plt.show()

galleries/nxdata/plot_image.py

@@ -0,0 +1,23 @@
+"""
+===============
+Image (2D Grid)
+===============
+
+Image (not necessarily evenly spaced)
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+plt.style.use("_mpl-gallery-nogrid")
+
+# make data
+X, Y = np.meshgrid(np.linspace(-3, 3, 16), np.linspace(-3, 3, 16))
+Z = (1 - X / 2 + X**5 + Y**3) * np.exp(-(X**2) - Y**2)
+
+# plot
+fig, ax = plt.subplots()
+
+ax.imshow(Z, origin="lower")
+
+plt.show()

manual/source/conf.py

@@ -48,7 +48,8 @@
     'sphinx.ext.githubpages',
     'sphinx.ext.todo',
     'sphinx_tabs.tabs',
-    'contrib_ext'
+    'contrib_ext',
+    'sphinx_gallery.gen_gallery'
 ]
 
 # Show `.. todo` directives in the output
@@ -109,3 +110,9 @@ def setup(app):
     \DeclareUnicodeCharacter{2906}{<=}
     \listfiles'''
 }
+
+# -- Options the gallery -------------------------------------------------
+sphinx_gallery_conf = {
+    'examples_dirs': '../../galleries/nxdata',  # path with .py files
+    'gallery_dirs': 'classes/base_classes/data',  # path where to save gallery generated output
+}

requirements.txt

@@ -7,6 +7,9 @@ nyaml
 sphinx>=5
 sphinx-tabs
 sphinx-toolbox
+sphinx-gallery
+matplotlib
+h5py
 
 # Testing
 pytest