Merge pull request #68 from kmnhan/docs

Documentation updates

.github/workflows/ci.yml

@@ -52,12 +52,12 @@ jobs:
       - name: Test with pytest
         if: matrix.python-version != '3.12' || matrix.qt-api != 'pyqt6'
         run: |
-          python -u -m pytest -vv --full-trace
+          python -u -m pytest -v
 
       - name: Test with pytest with coverage
         if: matrix.python-version == '3.12' && matrix.qt-api == 'pyqt6'
         run: |
-          python -u -m pytest -vv --full-trace --cov erlab --junitxml=junit.xml
+          python -u -m pytest -v --cov erlab --junitxml=junit.xml
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.12' && matrix.qt-api == 'pyqt6'

.readthedocs.yaml

@@ -6,7 +6,7 @@ version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.11"
 

docs/source/conf.py

@@ -128,7 +128,7 @@ def linkcode_resolve(domain, info) -> str | None:
 
 # -- Custom script to generate accessor docs ---------------------------------
 # Generates `erlab.accessors.rst` dynamically at build time
-def make_accessor_docs(app):
+def make_accessor_docs(app, config):
     import pathlib
     import subprocess
 
@@ -140,7 +140,7 @@ def make_accessor_docs(app):
 
 
 def setup(app):
-    app.connect("builder-inited", make_accessor_docs)
+    app.connect("config-inited", make_accessor_docs)
 
 
 # -- Autosummary and autodoc settings ----------------------------------------

docs/source/make_accessor_docs.py

@@ -96,7 +96,7 @@ def _make_section(table_content: str, header: str) -> str:
     if not table_content:
         return ""
 
-    return f"\n{header}\n{len(header) * "~"}\n\n.. list-table::\n{table_content}"
+    return f"\n{header}\n{len(header) * '~'}\n\n.. list-table::\n{table_content}"
 
 
 content = f"""Accessors (:mod:`erlab.accessors`)
@@ -106,13 +106,13 @@ def _make_section(table_content: str, header: str) -> str:
 
 Dataset accessors
 -----------------
-{_make_section(content_ds_methods, "Methods")}
-{_make_section(content_ds_attributes, "Attributes")}
+{_make_section(content_ds_methods, 'Methods')}
+{_make_section(content_ds_attributes, 'Attributes')}
 
 DataArray accessors
 -------------------
-{_make_section(content_da_methods, "Methods")}
-{_make_section(content_da_attributes, "Attributes")}
+{_make_section(content_da_methods, 'Methods')}
+{_make_section(content_da_attributes, 'Attributes')}
 
 """
 

docs/source/user-guide/io.ipynb

@@ -1000,10 +1000,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import glob\n",
+    "import pathlib\n",
     "import re\n",
     "\n",
     "from erlab.io.dataloader import LoaderBase\n",
+    "from erlab.utils.misc import emit_user_level_warning\n",
     "\n",
     "\n",
     "class ExampleLoader(LoaderBase):\n",
@@ -1063,20 +1064,26 @@
     "    always_single = False\n",
     "\n",
     "    def identify(self, num, data_dir):\n",
+    "        data_dir = pathlib.Path(data_dir)\n",
+    "\n",
     "        coord_dict = {}\n",
     "\n",
     "        # Look for scans with data_###_S###.h5, and sort them\n",
-    "        files = glob.glob(f\"data_{str(num).zfill(3)}_S*.h5\", root_dir=data_dir)\n",
-    "        files.sort()\n",
+    "        files = sorted(data_dir.glob(f\"data_{str(num).zfill(3)}_S*.h5\"))\n",
     "\n",
     "        if len(files) == 0:\n",
     "            # If no files found, look for data_###.h5\n",
-    "            files = glob.glob(f\"data_{str(num).zfill(3)}.h5\", root_dir=data_dir)\n",
-    "\n",
+    "            files = sorted(data_dir.glob(f\"data_{str(num).zfill(3)}.h5\"))\n",
+    "            if len(files) > 1:\n",
+    "                # More than one file found with the same scan number, show warning\n",
+    "                emit_user_level_warning(\n",
+    "                    f\"Multiple files found for scan {num}, using {files[0]}\"\n",
+    "                )\n",
+    "                files = files[:1]\n",
     "        else:\n",
     "            # If files found, extract coordinate values from the filenames\n",
-    "            axis_file = f\"{data_dir}/data_{str(num).zfill(3)}_axis.csv\"\n",
-    "            with open(axis_file) as f:\n",
+    "            axis_file = data_dir / f\"data_{str(num).zfill(3)}_axis.csv\"\n",
+    "            with axis_file.open(\"r\") as f:\n",
     "                header = f.readline().strip().split(\",\")\n",
     "\n",
     "            # Load the coordinates from the csv file\n",
@@ -1090,9 +1097,6 @@
     "            # If no files found up to this point, return None\n",
     "            return None\n",
     "\n",
-    "        # Files must be full paths\n",
-    "        files = [os.path.join(data_dir, f) for f in files]\n",
-    "\n",
     "        return files, coord_dict\n",
     "\n",
     "    def load_single(self, file_path, without_values=False):\n",
@@ -1269,7 +1273,7 @@
     "        darr = xr.open_dataarray(file_path, engine=\"h5netcdf\")\n",
     "\n",
     "        if without_values:\n",
-    "            # Do not load the data into memory\n",
+    "            # Prevent loading values into memory\n",
     "            return xr.DataArray(\n",
     "                np.zeros(darr.shape, darr.dtype),\n",
     "                coords=darr.coords,\n",

src/erlab/interactive/imagetool/__init__.py

@@ -282,7 +282,7 @@ def array_slicer(self) -> ArraySlicer:
         """  # noqa: D205
         return self.slicer_area.array_slicer
 
-    def to_pickle(self, filename: str) -> None:
+    def to_pickle(self, filename: str | os.PathLike) -> None:
         """Save the data, state, title, and geometry of the tool to a pickle file.
 
         The saved pickle file can be used to recreate the ImageTool with the class

src/erlab/interactive/imagetool/core.py

@@ -2147,14 +2147,12 @@ def save_current_data(self, fileName=None) -> None:
             self.fileDialog.setFileMode(QtWidgets.QFileDialog.FileMode.AnyFile)
             self.fileDialog.setAcceptMode(QtWidgets.QFileDialog.AcceptMode.AcceptSave)
             self.fileDialog.setNameFilter("xarray HDF5 Files (*.h5)")
-            if pg.PlotItem.lastFileDir is not None:
-                self.fileDialog.setDirectory(
-                    os.path.join(pg.PlotItem.lastFileDir, f"{default_name}.h5")
-                )
-            else:
-                self.fileDialog.setDirectory(
-                    os.path.join(os.getcwd(), f"{default_name}.h5")
-                )
+
+            last_dir = pg.PlotItem.lastFileDir
+            if not last_dir:
+                last_dir = os.getcwd()
+
+            self.fileDialog.setDirectory(os.path.join(last_dir, f"{default_name}.h5"))
             self.fileDialog.show()
             self.fileDialog.fileSelected.connect(self.save_current_data)
             return