Merge branch 'master' into mhanmer/operator_doc_template

Author: ansMHanmer

.ci/build_wheel.py

@@ -15,7 +15,8 @@
     "win": "win_amd64",
     "manylinux1": "manylinux1_x86_64",
     "manylinux_2_17": "manylinux_2_17_x86_64",
-    "linux": "manylinux_2_17_x86_64",  # Accommodate tox.ini platform substitutions
+    # Accommodate tox.ini automatic platform substitutions
+    "linux": "manylinux_2_17_x86_64",
     "win32": "win_amd64",
     "darwin": "any",
 }

doc/make.bat

@@ -9,6 +9,7 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=source
 set BUILDDIR=build
+set SPHINXOPTS=-n
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean

doc/source/user_guide/custom_operators.rst

@@ -249,5 +249,5 @@ Once the plugin is loaded, you can instantiate the custom operator:
 
 References
 ----------
-For more information, see :ref:`ref_custom_operator` in the **API reference**
+For more information, see :py:mod:`Custom Operator Base <ansys.dpf.core.custom_operator>` in the **API reference**
 and :ref:`python_operators` in **Examples**.

doc/source/user_guide/fields_container.rst

@@ -574,5 +574,5 @@ For comprehensive information on chaining operators, see :ref:`ref_user_guide_op
 
 API reference
 -------------
-For more information, see :ref:`ref_fields_container` and
-:ref:`ref_field` in the **API reference**.
+For more information, see :py:mod:`FieldsContainer <ansys.dpf.core.fields_container>` and
+:py:mod:`Field <ansys.dpf.core.field>` in the **API reference**.

doc/source/user_guide/model.rst

@@ -63,7 +63,7 @@ To understand what is available in the result file, you can print the model
 
 For a comprehensive model example, see :ref:`ref_basic_example`.
 
-For a description of the ``Model`` object, see :ref:`ref_model`.
+For a description of the ``Model`` object, see :py:mod:`Model <ansys.dpf.core.model>`.
 
 
 Model metadata
@@ -125,7 +125,7 @@ This example shows how you get time sets:
     [1.]
 
 
-For a description of the ``Metadata`` object, see :ref:`ref_model`.
+For a description of the ``Metadata`` object, see :py:mod:`Model <ansys.dpf.core.model>`.
 
 Model results
 -------------
@@ -176,11 +176,11 @@ the mesh scoping:
 
 For an example using the ``Result`` object, see :ref:`ref_transient_easy_time_scoping`.
 
-For a description of the ``Model`` object, see :ref:`ref_results`.
+For a description of the ``Model`` object, see :py:mod:`Model <ansys.dpf.core.model>`.
 
 
 
 API reference
 ~~~~~~~~~~~~~
 
-For more information, see :ref:`ref_model` or :ref:`ref_results`.
+For more information, see :py:mod:`Model <ansys.dpf.core.model>` or :py:mod:`Results <ansys.dpf.core.results>`.

doc/source/user_guide/operators.rst

@@ -59,9 +59,9 @@ which is progressively enhanced, see :ref:`ref_dpf_operators_reference`.
 
 Create operators
 ~~~~~~~~~~~~~~~~
-Each operator is of type :ref:`ref_operator`. You can create an instance 
+Each operator is of type :py:mod:`Operator <ansys.dpf.core.dpf_operator>`. You can create an instance 
 in Python with any of the derived classes available in the
-:ref:`ansys.dpf.core.operators package` or directly with the :ref:`ref_operator`
+:py:mod:`ansys.dpf.core.operators` package or directly with the :py:mod:`Operator <ansys.dpf.core.dpf_operator>`
 class using the internal name string that indicates the operator type. 
 For more information, see :ref:`ref_dpf_operators_reference`.
 
@@ -123,8 +123,8 @@ results, you must provide paths for the result files.
 
 You can create data sources in two ways:
 
-- Use the :ref:`ref_model` class.
-- Use the :ref:`ref_data_sources` class. 
+- Use the :py:mod:`Model <ansys.dpf.core.model>` class.
+- Use the :py:mod:`Data Sources <ansys.dpf.core.data_sources>` class. 
 
 
 Because several other examples use the ``Model`` class, this example uses the
@@ -154,7 +154,7 @@ This code demonstrates how to connect the data source to the displacement operat
     op.inputs.data_sources(data_src)
     
 You can connect other optional inputs to the displacement operator. 
-The output from printing the operator shows that a ``mesh_scoping`` of type :ref:`ref_scoping`
+The output from printing the operator shows that a ``mesh_scoping`` of type :py:mod:`Scoping <ansys.dpf.core.scoping>`
 can be connected to work on a spatial subset. A ``time_scoping`` of a list of integers 
 can also be connected to work on a temporal subset:
 
@@ -441,5 +441,5 @@ Python client is not on the same machine as the server:
 API reference
 ~~~~~~~~~~~~~
 For a list of all operators in DPF, see :ref:`ref_dpf_operators_reference` 
-or the package :ref:`ansys.dpf.core.operators package`.  For more information about the
-class itself, see :ref:`ref_operator`.
+or the package :py:mod:`ansys.dpf.core.operators`.  For more information about the
+class itself, see :py:mod:`Operator <ansys.dpf.core.dpf_operator>`.

src/ansys/dpf/core/helpers/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (C) 2020 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Provide helpers relating to streamline computation, argument filtering, and text indenting."""
+
+from .streamlines import *
+from .utils import *

src/ansys/dpf/core/model.py

@@ -24,7 +24,6 @@
 Model.
 
 Module contains the Model class to manage file result models.
-
 """
 
 from __future__ import annotations

tox.ini

@@ -1,15 +1,18 @@
 # This is work in progress, testing workflow in local/CI is gradually being transferred to tox
 
 # Usage instructions:
+
 # `tox` will run all tests sequentially, `tox --parallel` will run all tests in parallel (much faster).
 # Run specific selection of tests with `tox -e pretest,<list-of-tests>,posttest` e.g., `tox -e pretest,test-api,test-launcher,posttest`
 # `--parallel` flag can be passed when running specific selections.
 
+# For packaging, build wheels for specific platform with `tox -e build-wheel -- <platform_name>`.
+# If `tox -e build-wheel` is run without passing a platform, tox will automatically build the ffl wheels based on the operating system
+# on which it is executing: windows -> "win_amd64", linux -> "manylinux_2_17_x86_64", mac -> "any"
+
 [tox]
 description = Default tox environment list and core configurations
 
-# List all tests to run in parallel or sequential mode here
-# So invocation can be specified as `tox`/`tox --parallel` to run all tests in sequential/parallel mode
 envlist = pretest,test-{api,launcher,server,local_server,multi_server,remote_workflow,remote_operator,workflow,service,operators},posttest
 
 isolated_build_env = build
@@ -24,17 +27,6 @@ pass_env =
     ANSYSLMD_LICENSE_FILE
     AWP_ROOT242
 
-package = external # To allow custom wheel builds
-
-[testenv:build_external]
-description = Environment for custom build of package wheels, solves PyDPF custom wheel building requirement
-
-package_glob = {toxinidir}{/}dist{/}ansys_dpf_core*
-
-# {on_platform} substitution to automatically detect os type.
-commands = 
-    python .ci/build_wheel.py -p {on_platform} -w
-
 [testenv:pretest]
 description = Environment to kill servers and organize test files prior to testing
 
@@ -115,4 +107,71 @@ deps =
     -r requirements/requirements_test.txt
 
 commands =
-    pytest {env:PYTEST_PYTHON_FILES} {env:DEBUG} {env:COVERAGE} {env:RERUNS} {env:JUNITXML}
+    pytest {env:PYTEST_PYTHON_FILES} {env:DEBUG} {env:COVERAGE} {env:RERUNS} {env:JUNITXML}
+
+[testenv:doc-{clean,links,html}]
+description = Environment for documentation generation
+
+setenv =
+    SOURCE_DIR = doc/source
+    BUILD_DIR = doc/build
+    BUILDER_OPTS = --color -j auto
+    links: BUILDER = linkcheck
+    html: BUILDER = html
+
+skip_install =
+    clean: True
+
+deps =
+    links,html: -r requirements/requirements_docs.txt
+
+commands_pre =
+    # Clear any running servers that may be locking resources
+    html,links: python -c "import psutil; proc_name = 'Ans.Dpf.Grpc'; nb_procs = len([proc.kill() for proc in psutil.process_iter() if proc_name in proc.name()]); \
+    html,links: print(f'Killed \{nb_procs} \{proc_name} processes.')"
+
+commands =
+    # Remove previously rendered documentation
+    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
+
+    # Ensure vtk compatibility
+    html: python -m pip uninstall --yes vtk
+    html: python -m pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==9.2.20230527.dev0
+
+    # Clean files from previous build
+    html: python -c "\
+    html: from os.path import exists; import shutil; \
+    html: [(shutil.rmtree(p) if exists(p) else None) for p in ['{env:SOURCE_DIR}/images/auto-generated']]; \
+    html: [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    html: [('{env:SOURCE_DIR}/examples/07-python-operators/plugins', '{env:SOURCE_DIR}/_temp/plugins'), \
+    html: ('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress', '{env:SOURCE_DIR}/_temp/04_advanced'), \
+    html: ('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results', '{env:SOURCE_DIR}/_temp/12_fluids')]]; \
+    html: [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/examples'] if exists(p)]; \
+    html: [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    html: [('{env:SOURCE_DIR}/_temp/plugins', '{env:SOURCE_DIR}/examples/07-python-operators/plugins'), \
+    html: ('{env:SOURCE_DIR}/_temp/04_advanced', '{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress'), \
+    html: ('{env:SOURCE_DIR}/_temp/12_fluids', '{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results')]]; \
+    html: [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/_temp'] if exists(p)]"
+
+    # Build documentation
+    html,links: sphinx-build -b {env:BUILDER} {env:SOURCE_DIR} {env:BUILD_DIR}/{env:BUILDER} {env:BUILDER_OPTS}
+
+    # Patch pyVista issue with elemental plots by copying necessary images
+    html: python -c "\
+    html: import os, shutil, glob; os.makedirs('build/html/_images', exist_ok=True); \
+    html: [(shutil.copy(src, 'build/html/_images') if os.path.exists(src) else print(f'Source not found: {src}')) for src in \
+    html: glob.glob('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress/*') + glob.glob('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results/*')]"
+
+
+commands_post =
+    # Clear any running servers that may be locking resources
+    html,links: python -c "import psutil; proc_name = 'Ans.Dpf.Grpc'; nb_procs = len([proc.kill() for proc in psutil.process_iter() if proc_name in proc.name()]); \
+    html,links: print(f'Killed \{nb_procs} \{proc_name} processes.')"
+
+[testenv:build-wheel]
+description = Environment for custom build of package wheels
+
+skip_install = True
+
+commands = 
+    python .ci/build_wheel.py -p {posargs:{on_platform}} -w