added workflow for sphinx doc generation and fixed docstrings

Author: prasad-sawantdesai

.github/workflows/verify_sphinx_doc.yml

@@ -0,0 +1,56 @@
+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
+
+      - name: Deactivate virtual environment
+        run: deactivate

docs/source/changelog.rst

@@ -4,12 +4,12 @@ Changelog
 =========
 
 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:`imas.DBEntry.get_sample` previously imaspy.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,18 @@ 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.
+
+        Raises:
+            Exception: If the child entry cannot be found or an error occurs during retrieval.
+        """
         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 (str): The path to the data in the NetCDF file.
+            fillvalue (any): The value to fill the tensor with. Can be of any type,
+                             including strings.
+
+        Returns:
+            numpy.ndarray: 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,13 @@ 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 node for which the context or value is to be set. The child node should have metadata attributes.
+
+        """
         metadata = child.metadata
         path = metadata.path_string
         data_type = metadata.data_type
@@ -366,12 +373,43 @@ 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:
+            self: 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,))