feat(doc): improve operator Markdown documentation generation (#2635)

Author: PProfizi

.ci/generate_operators_doc.py

@@ -7,6 +7,7 @@ New-Item -Path ".\" -Name "test_remote_workflow" -ItemType "directory"
 New-Item -Path ".\" -Name "test_remote_operator" -ItemType "directory"
 New-Item -Path ".\" -Name "test_service" -ItemType "directory"
 New-Item -Path ".\" -Name "test_custom_type_field" -ItemType "directory"
+New-Item -Path ".\" -Name "test_documentation" -ItemType "directory"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_launcher\"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_server\"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_local_server\"
@@ -16,6 +17,7 @@ Copy-Item -Path "tests\conftest.py" -Destination ".\test_remote_workflow\"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_remote_operator\"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_service\"
 Copy-Item -Path "tests\conftest.py" -Destination ".\test_custom_type_field\"
+Copy-Item -Path "tests\conftest.py" -Destination ".\test_documentation\"
 Copy-Item -Path "tests\test_launcher.py" -Destination ".\test_launcher\"
 Copy-Item -Path "tests\test_server.py" -Destination ".\test_server\"
 Copy-Item -Path "tests\test_local_server.py" -Destination ".\test_local_server\"
@@ -25,6 +27,7 @@ Copy-Item -Path "tests\test_remote_workflow.py" -Destination ".\test_remote_work
 Copy-Item -Path "tests\test_remote_operator.py" -Destination ".\test_remote_operator\"
 Copy-Item -Path "tests\test_service.py" -Destination ".\test_service\"
 Copy-Item -Path "tests\test_custom_type_field.py" -Destination ".\test_custom_type_field\"
+Copy-Item -Path "tests\test_documentation.py" -Destination ".\test_documentation\"
 Remove-Item -Path "tests\test_server.py"
 Remove-Item -Path "tests\test_launcher.py"
 Remove-Item -Path "tests\test_local_server.py"
@@ -33,4 +36,5 @@ Remove-Item -Path "tests\test_workflow.py"
 Remove-Item -Path "tests\test_remote_workflow.py"
 Remove-Item -Path "tests\test_remote_operator.py"
 Remove-Item -Path "tests\test_service.py"
-Remove-Item -Path "tests\test_custom_type_field.py"
+Remove-Item -Path "tests\test_custom_type_field.py"
+Remove-Item -Path "tests\test_documentation.py"

.github/workflows/scripts/separate_long_core_tests.ps1

@@ -205,6 +205,15 @@ jobs:
           command: |
             pytest $DEBUG $COVERAGE $RERUNS --junitxml=../tests/junit/test-results12.xml tests/operators/.
 
+      - name: "Test Documentation"
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 4
+          max_attempts: 2
+          shell: bash
+          command: |
+            pytest $DEBUG $COVERAGE $RERUNS --junitxml=../tests/junit/test-results13.xml test_documentation/.
+
 #      - name: "Test API Entry"
 #        shell: bash
 #        working-directory: tests

.github/workflows/test_docker.yml

@@ -60,12 +60,20 @@ plotting = [
     "imageio-ffmpeg",
 ]
 
+operator_doc = [
+    # Operator documentation generation
+    "jinja2",
+]
+
 [project.urls]
 Homepage = "https://dpf.docs.pyansys.com/"
 Documentation = "https://dpf.docs.pyansys.com/"
 Source = "https://github.com/ansys/pydpf-core"
 Tracker = "https://github.com/ansys/pydpf-core/issues"
 
+[project.scripts]
+dpf_generate_operators_doc = "ansys.dpf.core.documentation.generate_operators_doc:run_with_args"
+
 [tool.ruff]
 line-length = 100
 
@@ -115,4 +123,5 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 "ansys.dpf.gatebin" = ["*.so", "*.dll"]
+"ansys.dpf.core.documentation" = ["toc_template.j2", "operator_doc_template.md"]
 

pyproject.toml

@@ -3,6 +3,7 @@ coverage==7.10.6
 graphviz==0.21
 imageio==2.37.0
 imageio-ffmpeg==0.6.0
+jinja2==3.1.6
 pypandoc_binary==1.15
 pytest==8.4.2
 pytest-cov==6.2.1

requirements/requirements_test.txt

@@ -99,6 +99,7 @@
     AvailableServerContexts,
     LicenseContextManager
 )
+from ansys.dpf.core.server_types import AnyServerType  # noqa: F401
 from ansys.dpf.core.unit_system import UnitSystem, unit_systems
 from ansys.dpf.core.incremental import IncrementalHelper, split_workflow_in_chunks
 from ansys.dpf.core.any import Any

src/ansys/dpf/core/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+"""Documentation generation tools."""