Merge branch 'develop' into release/2.0.0

Author: olivhoenen

.github/workflows/verify_sphinx_doc.yml

@@ -0,0 +1,53 @@
+name: verify-sphinx-doc-generation
+
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout IMAS-Python sources
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          with:
+          # until saxonche is available in 3.13
+          # https://saxonica.plan.io/issues/6561
+          python-version: "<3.13"
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+
+      - name: Set up Python virtual environment
+        run: |
+          python -m venv venv
+          source venv/bin/activate
+
+      - name: Install build dependencies
+        run: |
+          pip install --upgrade pip setuptools wheel build
+
+      - name: Build package
+        run: |
+          rm -rf dist
+          python -m build .
+
+      - name: Install package and dependencies
+        run: |
+          pip install "$(readlink -f dist/*.whl)[docs,netcdf]"
+
+      - name: Debug dependencies
+        run: |
+          pip freeze
+
+      - name: Build Sphinx documentation
+        run: |
+          export SPHINXOPTS='-W -n --keep-going'
+          make -C docs clean html

docs/source/changelog.rst

@@ -29,7 +29,7 @@ What's new in IMAS-Python 1.2.0
 New features and improvements
 '''''''''''''''''''''''''''''
 
-- Add :py:func:`imaspy.DBEntry.get_sample` (requires imas_core >= 5.4.0)
+- Add :py:func:`imaspy.DBEntry.get_sample <imas.db_entry.DBEntry.get_sample>` (requires imas_core >= 5.4.0)
 - Improved validation of netCDF files
 - Improve compatibility with the UDA backend in imas_core
 - Extend the support of netCDF to >= 1.4.1 (without complex numbers)

imas/backends/imas_core/al_context.py

@@ -282,6 +282,15 @@ def __init__(
         """Potential weak reference to opened context."""
 
     def get_child(self, child):
+        """
+        Retrieve a child entry from the field.
+
+        Args:
+            child (str): The name or identifier of the child entry to retrieve.
+
+        Returns:
+            The child entry retrieved from the database.
+        """
         imas.backends.imas_core.db_entry_helpers._get_child(child, self)
 
     def get_context(self) -> ALContext:

imas/backends/netcdf/ids_tensorizer.py

@@ -169,6 +169,17 @@ def filter_coordinates(self, path: str) -> str:
         )
 
     def tensorize(self, path, fillvalue):
+        """
+        Tensorizes the data at the given path with the specified fill value.
+
+        Args:
+            path: The path to the data in the IDS.
+            fillvalue: The value to fill the tensor with. Can be of any type,
+                             including strings.
+
+        Returns:
+            A tensor filled with the data from the specified path.
+        """
         dimensions = self.ncmeta.get_dimensions(path, self.homogeneous_time)
         shape = tuple(self.dimension_size[dim] for dim in dimensions)
 

imas/backends/netcdf/nc2ids.py

@@ -317,6 +317,14 @@ def __init__(self, nc2ids, index=()):
         self.index = index
 
     def get_child(self, child):
+        """
+        Retrieves and sets the appropriate context or value for a given
+        child node based on its metadata.
+
+        Args:
+            child: The child IDS node which should be lazy loaded.
+
+        """
         metadata = child.metadata
         path = metadata.path_string
         data_type = metadata.data_type
@@ -366,12 +374,44 @@ def get_child(self, child):
 
 
 class LazyArrayStructContext(LazyContext):
+    """
+    LazyArrayStructContext is a subclass of LazyContext that provides a context for
+    handling structured arrays in a lazy manner. It is initialized with a NetCDF to
+    IDS mapping object, an index, and a size.
+    """
+
     def __init__(self, nc2ids, index, size):
+        """
+        Initialize the instance with nc2ids, index, and size.
+
+        Args:
+            nc2ids: The NetCDF to IDS mapping object.
+            index: The index within the NetCDF file.
+            size: The size of the data to be processed.
+        """
         super().__init__(nc2ids, index)
         self.size = size
 
     def get_context(self):
+        """
+        Returns the current context.
+
+        This method returns the current instance of the class, which is expected
+        to have a 'size' attribute as required by IDSStructArray.
+
+        Returns:
+            The current instance of the class.
+        """
         return self  # IDSStructArray expects to get something with a size attribute
 
     def iterate_to_index(self, index: int) -> LazyContext:
+        """
+        Iterates to a specified index and returns a LazyContext object.
+
+        Args:
+            index (int): The index to iterate to.
+
+        Returns:
+            LazyContext: A LazyContext object initialized with the updated index.
+        """
         return LazyContext(self.nc2ids, self.index + (index,))