feat(operator_doc): include operator usage examples in the operator documentation (#2777)

Author: PProfizi

src/ansys/dpf/core/documentation/generate_operators_doc.py

@@ -33,6 +33,7 @@
 from ansys.dpf.core.changelog import Changelog
 from ansys.dpf.core.core import load_library
 from ansys.dpf.core.dpf_operator import available_operator_names
+from ansys.dpf.core.mapping_types import reflection_type_to_cpp_type
 
 
 class Jinja2ImportError(ModuleNotFoundError):  # pragma: nocover
@@ -233,22 +234,27 @@ def fetch_doc_info(server: dpf.AnyServerType, operator_name: str) -> dict:
     configurations_info = []
     for input_pin in spec.inputs:
         input_pin_info = spec.inputs[input_pin]
+        input_type_names = input_pin_info._type_names
         input_info.append(
             {
                 "pin_number": input_pin,
                 "name": input_pin_info.name,
-                "types": [str(t) for t in input_pin_info._type_names],
+                "types": [str(t) for t in input_type_names],
+                "cpp_types": [reflection_type_to_cpp_type(t) for t in input_type_names],
                 "document": input_pin_info.document,
                 "optional": input_pin_info.optional,
+                "ellipsis": input_pin_info.ellipsis,
             }
         )
     for output_pin in spec.outputs:
         output = spec.outputs[output_pin]
+        output_type_names = output._type_names
         output_info.append(
             {
                 "pin_number": output_pin,
                 "name": output.name,
-                "types": [str(t) for t in output._type_names],
+                "types": [str(t) for t in output_type_names],
+                "cpp_types": [reflection_type_to_cpp_type(t) for t in output_type_names],
                 "document": output.document,
                 "optional": output.optional,
             }

src/ansys/dpf/core/documentation/operator_doc_template.j2

@@ -59,6 +59,60 @@ This operator supports the following keys ([file formats](../../index.md#overvie
 
  **License**: {{ scripting_info.license }}
 
+## Examples
+
+<details>
+<summary>C++</summary>
+
+```cpp
+#include "dpf_api.h"
+
+ansys::dpf::Operator op("{{ scripting_info.internal_name }}"); // operator instantiation
+{%- for input in inputs %}
+op.connect({{ input.pin_number }}, my_{{ input.name }});
+{%- endfor %}
+{%- for output in outputs %}
+{{ output.cpp_types[0] }} my_{{ output.name }} = op.getOutput<{{ output.cpp_types[0] }}>({{ output.pin_number }});
+{%- endfor %}
+```
+</details>
+
+<details>
+<summary>CPython</summary>
+
+```python
+import ansys.dpf.core as dpf
+
+op = dpf.operators.{{ scripting_info.category }}.{{ scripting_info.scripting_name }}() # operator instantiation
+
+{%- for input in inputs %}
+{% if input.ellipsis %}op.inputs.{{ input.name }}1.connect(my_{{ input.name }}1)
+op.inputs.{{ input.name }}2.connect(my_{{ input.name }}2){% else%}op.inputs.{{ input.name }}.connect(my_{{ input.name }}){% endif %}
+{%- endfor %}
+{%- for output in outputs %}
+{% if output.types|length > 1 %}my_{{ output.name }}_as_{{ output.types[0] }} = op.outputs.{{ output.name }}_as_{{ output.types[0] }}(){% else %}my_{{ output.name }} = op.outputs.{{ output.name }}(){% endif %}
+{%- endfor %}
+```
+</details>
+
+<details>
+<summary>IPython</summary>
+
+```python
+import mech_dpf
+import Ans.DataProcessing as dpf
+
+op = dpf.operators.{{ scripting_info.category }}.{{ scripting_info.scripting_name }}() # operator instantiation
+
+{%- for input in inputs %}
+op.inputs.{{ input.name }}.Connect(my_{{ input.name }})
+{%- endfor %}
+{%- for output in outputs %}
+my_{{ output.name }} = op.outputs.{{ output.name }}.GetData()
+{%- endfor %}
+```
+</details>
+<br>
 
 ## Changelog
 

src/ansys/dpf/core/mapping_types.py

@@ -76,3 +76,39 @@ def __missing__(self, key):
 map_types_to_python["vector<double>"] = "list[float]"
 map_types_to_python["vector<string>"] = "list[str]"
 map_types_to_python["b"] = "bool"
+
+
+def reflection_type_to_cpp_type(reflection_type: str) -> str:
+    """Convert a reflection type to its corresponding C++ type.
+
+    The reflection type is obtained from the server specification of the operator.
+
+    Used to generate the C++ code examples in the operator documentation.
+
+    Parameters
+    ----------
+    reflection_type : str
+        The reflection type to convert.
+
+    Returns
+    -------
+    str
+        The corresponding C++ type.
+    """
+    if reflection_type == "abstract_meshed_region":
+        reflection_type = "meshed_region"
+    if reflection_type == "streams_container":
+        reflection_type = "streams"
+    if reflection_type == "int32":
+        return "int"
+    elif reflection_type in ["double", "bool"]:
+        return reflection_type
+    elif reflection_type == "string":
+        return "std::string"
+    elif reflection_type[:7] == "vector<":
+        inner_type = reflection_type[7:-1]
+        cpp_inner_type = reflection_type_to_cpp_type(inner_type)
+        return f"std::vector<{cpp_inner_type}>"
+    else:
+        reflection_type = f"ansys::dpf::{_snake_to_camel_case(reflection_type)}"
+    return reflection_type