Merge branch 'main' into feat/support-windows-based-containers

Author: moe-ad

.github/workflows/docs.yml

@@ -79,7 +79,7 @@ jobs:
       - name: "Build the wheel"
         shell: pwsh
         run: |
-          tox -e build-wheel
+          tox -e build-wheel -- "any"
 
       - name: "Expose the wheel"
         shell: bash

doc/source/_static/dpf_operators.html

@@ -5,7 +5,7 @@ requires = ["setuptools>=61.0.0", "wheel"]
 [project]
 # Check https://setuptools.pypa.io/en/stable/userguide/quickstart.html for all available sections
 name = "ansys-dpf-core"
-version = "0.14.2.dev0"
+version = "0.14.3.dev0"
 description = "Data Processing Framework - Python Core "
 readme = "README.md"
 requires-python = ">=3.9, <4"

pyproject.toml

@@ -1,4 +1,4 @@
-black==25.1.0
+black==25.9.0
 build==1.3.0
 chevron==0.14.0
 pypandoc_binary==1.15

requirements/requirements_build.txt

@@ -1,4 +1,4 @@
-ansys-sphinx-theme[autoapi]==1.5.3
+ansys-sphinx-theme[autoapi]==1.6.3
 enum-tools[sphinx]==0.13.0
 graphviz==0.21
 imageio==2.37.0
@@ -7,7 +7,7 @@ jupyter_sphinx==0.5.3
 nbsphinx==0.9.5
 pypandoc==1.15
 pytest-sphinx==0.6.3
-pyvista==0.46.1
+pyvista==0.46.3
 sphinx==8.2.3
 sphinx-copybutton==0.5.2
 sphinx-gallery==0.19.0

requirements/requirements_docs.txt

@@ -1,5 +1,5 @@
 importlib-metadata==8.7.0
-numpy==2.2.4
+numpy==2.3.4
 packaging==25.0
-psutil==7.0.0
+psutil==7.1.1
 tqdm==4.67.1

requirements/requirements_install.txt

@@ -1,5 +1,5 @@
 ansys-platform-instancemanagement==1.1.2
-coverage==7.10.6
+coverage==7.11.0
 graphviz==0.21
 imageio==2.37.0
 imageio-ffmpeg==0.6.0
@@ -8,6 +8,6 @@ pypandoc_binary==1.15
 pytest==8.4.2
 pytest-cov==6.2.1
 pytest-order==1.3.0
-pytest-rerunfailures==16.0.1
-pyvista==0.46.1
+pytest-rerunfailures==16.1
+pyvista==0.46.3
 vtk==9.4.2

requirements/requirements_test.txt

@@ -109,17 +109,16 @@
 from ansys.dpf.core.dpf_operator import available_operator_names
 
 
-from ansys.dpf.core.collection import CollectionFactory as _CollectionFactory
 from ansys.dpf.core.collection import Collection as _Collection
 from ansys.dpf.core.label_space import LabelSpace
 
 
 # register classes for collection types:
-CustomTypeFieldsCollection:type = _CollectionFactory(CustomTypeField)
-GenericDataContainersCollection:type = _CollectionFactory(GenericDataContainer)
-StringFieldsCollection:type = _CollectionFactory(StringField)
-OperatorsCollection: type = _CollectionFactory(Operator)
-AnyCollection:type = _Collection
+CustomTypeFieldsCollection = _Collection.collection_factory(CustomTypeField)
+GenericDataContainersCollection = _Collection.collection_factory(GenericDataContainer)
+StringFieldsCollection = _Collection.collection_factory(StringField)
+OperatorsCollection = _Collection.collection_factory(Operator)
+AnyCollection = _Collection
 
 # for matplotlib
 # solves "QApplication: invalid style override passed, ignoring it."

src/ansys/dpf/core/__init__.py

@@ -25,13 +25,18 @@
 
 from __future__ import annotations
 
+from typing import Generic, Type, TypeVar
+
 from ansys.dpf.core import errors, server as server_module
 from ansys.dpf.core.any import Any
-from ansys.dpf.core.collection_base import TYPE, CollectionBase
+from ansys.dpf.core.collection_base import CollectionBase
 from ansys.dpf.core.common import create_dpf_instance
 
+TYPE = TypeVar("TYPE")
+
 
-class Collection(CollectionBase[TYPE]):
+# Explicit Generic[TYPE] helps some type checkers Collection as a generic.
+class Collection(CollectionBase[TYPE], Generic[TYPE]):
     """Represents a collection of dpf objects organised by label spaces.
 
     Parameters
@@ -120,16 +125,39 @@ def add_entry(self, label_space, entry):
         """
         return super()._add_entry(label_space, Any.new_from(entry, server=self._server))
 
+    @classmethod
+    def collection_factory(cls, subtype: TYPE) -> Type[Collection[TYPE]]:
+        """Create classes deriving from Collection at runtime for a given subtype.
 
-def CollectionFactory(subtype, BaseClass=Collection):
-    """Create classes deriving from Collection at runtime for a given subtype."""
+        This factory method dynamically creates a new class that inherits from Collection
+        and is specialized for storing entries of the specified subtype.
 
-    def __init__(self, **kwargs):
-        BaseClass.__init__(self, **kwargs)
+        Parameters
+        ----------
+        subtype : type
+            Any recognized DPF type. For example, CustomTypeField, GenericDataContainer,
+            StringField, Operator, etc. This type will be used as the entries_type for
+            the new collection class.
 
-    new_class = type(
-        str(subtype.__name__) + "sCollection",
-        (BaseClass,),
-        {"__init__": __init__, "entries_type": subtype},
-    )
-    return new_class
+        Returns
+        -------
+        Type[Collection[TYPE]]
+            A new class that inherits from Collection and is specialized for the given
+            subtype. The class name will be "{subtype.__name__}sCollection".
+
+        Examples
+        --------
+        >>> from ansys.dpf.core.string_field import StringField
+        >>> from ansys.dpf.core.collection import Collection
+        >>> string_fields_collection = Collection.collection_factory(StringField)()
+        >>> string_fields_collection.__class__.__name__
+        'StringFieldsCollection'
+        >>> string_fields_collection.entries_type.__name__
+        'StringField'
+        """
+        new_class = type(
+            str(subtype.__name__) + "sCollection",
+            (cls,),
+            {"entries_type": subtype},
+        )
+        return new_class

src/ansys/dpf/core/collection.py

@@ -120,7 +120,9 @@ def extract_operator_description_update(content: str) -> str:
             The updated description to use for the operator.
     """
     match = re.search(r"## Description\s*(.*?)\s*(?=## |\Z)", content, re.DOTALL)
-    return match.group(0) + os.linesep if match else None
+    description = match.group(0) + os.linesep if match else None
+    # Handle unicode characters
+    return description.encode("unicode-escape").decode()
 
 
 def replace_operator_description(original_documentation: str, new_description: str):
@@ -293,9 +295,11 @@ def fetch_doc_info(server: dpf.AnyServerType, operator_name: str) -> dict:
         "changelog": changelog_entries,  # Include all changelog entries
     }
 
+    op_description = latex_to_dollars(spec.description)
+
     return {
         "operator_name": op_friendly_name,
-        "operator_description": spec.description,
+        "operator_description": op_description,
         "inputs": input_info,
         "outputs": output_info,
         "configurations": configurations_info,
@@ -304,6 +308,19 @@ def fetch_doc_info(server: dpf.AnyServerType, operator_name: str) -> dict:
     }
 
 
+def latex_to_dollars(text: str) -> str:
+    r"""Convert LaTeX math delimiters from \\[.\\] to $$.$$ and from \\(.\\) to $.$ in a given text.
+
+    Parameters
+    ----------
+    text:
+        The input text containing LaTeX math delimiters.
+    """
+    return (
+        text.replace(r"\\[", "$$").replace(r"\\]", "$$").replace(r"\\(", "$").replace(r"\\)", "$")
+    )
+
+
 def get_plugin_operators(server: dpf.AnyServerType, plugin_name: str) -> list[str]:
     """Get the list of operators for a given plugin.
 
@@ -348,7 +365,7 @@ def generate_operator_doc(
     """
     operator_info = fetch_doc_info(server, operator_name)
     scripting_name = operator_info["scripting_info"]["scripting_name"]
-    category = operator_info["scripting_info"]["category"]
+    category: str = operator_info["scripting_info"]["category"]
     if scripting_name:
         file_name = scripting_name
     else:
@@ -391,7 +408,10 @@ def update_toc_tree(docs_path: Path):
             operators = []  # Reset operators for each category
             for file in folder.iterdir():
                 if (
-                    file.is_file() and file.suffix == ".md" and not file.name.endswith("_upd.md")
+                    file.is_file()
+                    and file.suffix == ".md"
+                    and not file.name.endswith("_upd.md")
+                    and not file.name.endswith("_category.md")
                 ):  # Ensure 'file' is a file with .md extension
                     file_name = file.name
                     file_path = f"{category}/{file_name}"
@@ -419,6 +439,60 @@ def update_toc_tree(docs_path: Path):
         file.write(new_toc)
 
 
+def update_categories(docs_path: Path):
+    """Update the category index files for the operator specifications.
+
+    Parameters
+    ----------
+    docs_path:
+        Path to the root of the DPF documentation sources.
+
+    """
+    specs_path = docs_path / Path("operator-specifications")
+    for folder in specs_path.iterdir():
+        if folder.is_dir():  # Ensure 'folder' is a directory
+            category = folder.name
+            operators = []  # Reset operators for each category
+            for file in folder.iterdir():
+                if (
+                    file.is_file()
+                    and file.suffix == ".md"
+                    and not file.name.endswith("_upd.md")
+                    and not file.name.endswith("_category.md")
+                ):  # Ensure 'file' is a file with .md extension
+                    file_name = file.name
+                    operator_name = file_name.replace("_", " ").replace(".md", "")
+                    operators.append({"operator_name": operator_name, "file_path": file_name})
+            # Update category index file
+            category_file_path = folder / f"{category}_category.md"
+            with category_file_path.open(mode="w") as cat_file:
+                cat_file.write(f"# {category.capitalize()} operators\n\n")
+                for operator in operators:
+                    cat_file.write(f"- [{operator['operator_name']}]({operator['file_path']})\n")
+
+
+def update_operator_index(docs_path: Path):
+    """Update the main index file for all operator specifications.
+
+    Parameters
+    ----------
+    docs_path:
+        Path to the root of the DPF documentation sources.
+
+    """
+    specs_path = docs_path / Path("operator-specifications")
+    index_file_path = specs_path / "operator-specifications.md"
+    with index_file_path.open(mode="w") as index_file:
+        index_file.write("# Operator Specifications\n\n")
+        for folder in specs_path.iterdir():
+            if folder.is_dir():  # Ensure 'folder' is a directory
+                category = folder.name
+                index_file.write(
+                    f"- [{category.capitalize()} operators]({category}/{category}_category.md)\n\n"
+                )
+                index_file.write("\n")
+
+
 def generate_operators_doc(
     output_path: Path,
     ansys_path: Path = None,
@@ -461,6 +535,10 @@ def generate_operators_doc(
         generate_operator_doc(server, operator_name, include_private, output_path)
     # Generate the toc tree
     update_toc_tree(output_path)
+    # Generate the category index files
+    update_categories(output_path)
+    # Generate the main index file for all categories
+    update_operator_index(output_path)
     # Use update files in output_path
     update_operator_descriptions(output_path)