feat: adding warning info at the top of a command

Author: clatapie

config.yaml

@@ -20,20 +20,42 @@ specific_command_mapping:
   "/INQUIRE": inquire
 
 ignored_commands:
-  - "*VWR"
-  - "*MWR"
-  - "C***"
-  - "*CFO"
-  - "*CRE"
-  - "*END"
-  - "/EOF"
+  # Non-available commands - PyMAPDL user guide
   - "*ASK"
-  - "*IF"
+  - "*VEDIT"
+  - "/ERASE"
+  - "ERASE"
+  - "HELP"
+  - "HELPDISP"
+  - "NOERASE"
+  - "*CYCLE"
+  - "*DO"
+  - "*DOWHILE"
   - "*ELSE"
-  - "CMAT"
-  - "*REP"
+  - "*ELSEIF"
+  - "*ENDDO"
+  - "*GO"
+  - "*IF"
+  - "*REPEAT"
   - "*RETURN"
-  - "LSRE"
+  - "*DEL"
+  - "/BATCH"
+  - "/EOF"
+  - "UNDO"
+  # Additional commands to ignore
+  - "C***"
+  - "/DIRECTORY" # Defined in ``mapdl_core.py``
+  - "*XPL" # Defined in ``mapdl_grpc.py``
+
+warnings:
+  "This command must be run using :func:`non_interactive <ansys.mapdl.core.Mapdl.non_interactive>`\nPlease visit `Unsupported Interactive Commands <https://mapdl.docs.pyansys.com/version/stable/user_guide/mapdl.html#unsupported-interactive-commands>`_\nfor further information.":
+    - "*CREATE"
+    - "CFOPEN"
+    - "CFCLOSE"
+    - "*VWRITE"
+    - "*MWRITE"
+    - "LSWRITE"
+    - "LSREAD"
 
 
 specific_classes:

src/pyconverter/xml2py/ast_tree.py

@@ -2898,12 +2898,35 @@ def py_signature(self, custom_functions: CustomFunctions, indent="") -> str:
         arg_sig = ", ".join(args)
         return f"{indent}def {self.py_name}({arg_sig}, **kwargs):"
 
-    def py_docstring(self, custom_functions: CustomFunctions) -> str:
-        """Python docstring of the command."""
+    def py_docstring(self, custom_functions: CustomFunctions, warning_command_dict: None) -> str:
+        """
+        Python docstring of the command.
+
+        Parameters
+        ----------
+
+        custom_functions : CustomFunctions
+            Custom functions object.
+
+        warning_command_dict: dict, optional
+            Dictionary of commands associated to a list of warnings.
+            The default is ``None``.
+
+
+        """
         xml_cmd = f"{self._terms['pn006p']} Command: `{self.name} <{self.url}>`_"
 
+        # ``warning_command_dict`` need to be added here
+
         items = [self.short_desc, "", xml_cmd]
 
+        if self.name in warning_command_dict.keys():
+            warnings_ = warning_command_dict[self.name]
+            for warning_ in warnings_:
+                warning_ = textwrap.indent(warning_, " " * 3)
+                items.extend([f"\n.. warning::\n{warning_}\n"])
+                print(items)
+
         if self.default is not None:
             if self.default.tag in item_needing_links_base_url:
                 items += [""] + textwrap.wrap(
@@ -3247,14 +3270,20 @@ def py_source(self, custom_functions=None, indent=""):
             source = textwrap.indent("".join(custom_functions.py_code[self.py_name]), prefix=indent)
         return source
 
-    def to_python(self, custom_functions=None, indent=""):
+    def to_python(self, custom_functions=None, warning_command_dict=None, indent=""):
         """
         Return the complete Python definition of the command.
 
         Parameters
         ----------
         custom_functions: CustomFunctions, optional
-            Custom functions to add to the command. The default is ``None``.
+            Custom functions to add to the command.
+            The default is ``None``.
+
+        warning_command_dict: dict, optional
+            Dictionary of commands associated to a list of warnings.
+            The default is ``None``.
+
         indent: str, optional
             Indentation of the Python function. The default is ``""``.
 
@@ -3265,7 +3294,8 @@ def to_python(self, custom_functions=None, indent=""):
         """
 
         docstr = textwrap.indent(
-            f'r"""{self.py_docstring(custom_functions)}\n"""', prefix=indent + " " * 4
+            f'r"""{self.py_docstring(custom_functions, warning_command_dict)}\n"""',
+            prefix=indent + " " * 4,
         )
         if custom_functions is not None and self.py_name in custom_functions.lib_import:
             imports = "\n".join(custom_functions.lib_import[self.py_name])

src/pyconverter/xml2py/utils/utils.py

@@ -64,6 +64,27 @@ def get_config_data_value(yaml_path: Path, value: str) -> Union[str, dict, list,
     return config_data.get(value)
 
 
+def get_warning_command_dict(yaml_path: Path) -> dict:
+    """
+    Get the list of commands that will raise a warning.
+
+    Parameters
+    ----------
+    yaml_path: Path
+        Path object of the YAML file.
+    """
+    warnings_ = get_config_data_value(yaml_path, "warnings")
+    warning_command_dict = {}
+    for warning_, command_list in warnings_.items():
+        for command in command_list:
+            try:
+                warning_command_dict[command].append(warning_)
+            except KeyError:
+                warning_command_dict[command] = [warning_]
+
+    return warning_command_dict
+
+
 def create_name_map(meta_command: list[str], yaml_file_path: Path) -> dict:
     """
     Create a mapping between the initial command name and the Python function name.

src/pyconverter/xml2py/writer.py

@@ -35,6 +35,7 @@
     create_name_map,
     get_config_data_value,
     get_refentry,
+    get_warning_command_dict,
     import_handler,
 )
 import regex as re
@@ -430,6 +431,8 @@ def write_source(
 
     library_path = Path(get_library_path(new_package_path, config_path))
 
+    warning_command_dict = get_warning_command_dict(config_path)
+
     if not library_path.is_dir():
         library_path.mkdir(parents=True, exist_ok=True)
 
@@ -440,7 +443,7 @@ def write_source(
                 continue
             python_name = name_map[initial_command_name]
             path = library_path / f"{python_name}.py"
-            python_method = command_obj.to_python(custom_functions)
+            python_method = command_obj.to_python(custom_functions, warning_command_dict, indent="")
             try:
                 exec(python_method)
                 with open(path, "w", encoding="utf-8") as fid:
@@ -482,7 +485,9 @@ def write_source(
             class_structure.append(command.py_name)
 
             package_structure[module_name][file_name] = [class_name, class_structure]
-            python_method = command.to_python(custom_functions, indent=4 * " ")
+            python_method = command.to_python(
+                custom_functions, warning_command_dict, indent=4 * " "
+            )
 
             # Check if there are any imports to be added before the function definition.
             reg_before_def = pat.BEFORE_DEF + f"{command.py_name})"