DOCS: Update documentation for Desktop.get_example (#6712)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Samuel Lopez <[email protected]>

Author: 3 people

doc/changelog.d/6712.documentation.md

@@ -0,0 +1 @@
+Update documentation for Desktop.get_example

src/ansys/aedt/core/application/design.py

@@ -3701,7 +3701,7 @@ def copy_design_from(self, project, design, save_project=True, set_active_design
 
         Parameters
         ----------
-        project : str
+        project : pathlib.Path or str
             Full path and name for the project containing the design to copy.
             The active design is maintained.
         design : str
@@ -3906,7 +3906,7 @@ def save_project(self, file_name=None, overwrite=True, refresh_ids=False):
 
         Parameters
         ----------
-        file_name : str, optional
+        file_name : str or pathlib.Path, optional
             Full path and project name. The default is ````None``.
         overwrite : bool, optional
             Whether to overwrite the existing project. The default is ``True``.

src/ansys/aedt/core/desktop.py

@@ -723,12 +723,28 @@ def get_example(self, example_name, folder_name="."):
         example_name : str
             Name of the example for which the full path is desired.
         folder_name : str, optional
-            Name of the example for which the full path is desired.
+            Name of the subfolder in the ``"Examples"`` folder where the example having
+            ``example_name`` can be found. The default is ``"."`` which points to
+            ``self.install_path / "Examples"``
 
         Returns
         -------
-        str
-            Return the full path and name of the example file if found, otherwise ``None``.
+        pathlib.Path
+            Return the path to the example file if found, otherwise ``None``.
+
+        Examples
+        --------
+        Create a copy of a built-in example.
+
+        >>> import shutil
+        >>> from ansys.aedt.core import Desktop
+        >>> from pathlib import Path
+        >>> working_folder = Path("C:\") / "path" / "to" / "target_folder"  # Windows
+        >>> d = Desktop(version=252)
+        >>> example_path = d.get_example("5G_SIW_Aperture_Antenna")
+        >>> new_project = working_folder / example_path.name
+        >>> working_folder.mkdir(parents=True, exist_ok=True)
+        >>> shutil.copytree(example_path, new_project)  # Copy example to new working folder.
         """
         root = Path(self.install_path) / "Examples" / folder_name
 
@@ -747,7 +763,7 @@ def get_example(self, example_name, folder_name="."):
             # Find the original Path object that matches the filename (case-insensitive)
             for file in all_files:
                 if file.name.lower() == match_name:
-                    return str(file.resolve())
+                    return file.resolve()
 
     @property
     def logger(self):

tests/system/general/test_01_Design.py

@@ -217,11 +217,11 @@ def test_15b_copy_design_from(self, aedtapp, local_scratch):
         assert len(aedtapp.design_list) == 1
 
     def test_15c_copy_example(self, aedtapp):
-        example_name = aedtapp.desktop_class.get_example("5G_SIW_Aperture_Antenna")
+        example_project = aedtapp.desktop_class.get_example("5G_SIW_Aperture_Antenna")
         from ansys.aedt.core.generic.file_utils import remove_project_lock
 
-        remove_project_lock(example_name)
-        aedtapp.copy_design_from(example_name, "0_5G Aperture Element")
+        remove_project_lock(example_project)
+        aedtapp.copy_design_from(str(example_project), "0_5G Aperture Element")
         assert aedtapp.design_name == "0_5G Aperture Element"
         assert not aedtapp.desktop_class.get_example("fake")