feat: enabling different types of message to be added at the beginning of a docstring

Author: clatapie

config.yaml

@@ -50,12 +50,13 @@ ignored_commands:
   - "/DIRECTORY" # Defined in ``mapdl_core.py``
   - "*XPL" # Defined in ``mapdl_grpc.py``
 
-warnings:
-  - msg: 'This command must be run using :func:`non_interactive <ansys.mapdl.core.Mapdl.non_interactive>
+beginning_comments:
+  - msg: 'This command must be run using :func:`non_interactive <ansys.mapdl.core.Mapdl.non_interactive>`.
 
-    Please visit `Unsupported Interactive Commands <https://mapdl.docs.pyansys.com/version/stable/user_guide/mapdl.html#unsupported-interactive-commands>`_
+          Please visit `Unsupported Interactive Commands <https://mapdl.docs.pyansys.com/version/stable/user_guide/mapdl.html#unsupported-interactive-commands>`_
     
-    for further information.'
+          for further information.'
+    type: "warning"
     commands:
       - "*CREATE"
       - "CFOPEN"
@@ -65,6 +66,14 @@ warnings:
       - "LSWRITE"
       - "LSREAD"
 
+  - msg: 'Starting with PyMAPDL v0.66.0, you can use "P" as a second argument to select entities interactively. A window pops up
+          
+          allowing you to select, unselect, add or reselect entities depending on the first argument ``type_``. An array with
+          
+          the ids of new selection is returned when the window is closed.'
+    type: "note"
+    commands:
+     - "ASEL"
 
 specific_classes:
   2D to 3D Analysis: Analysis 2D to 3D

src/pyconverter/xml2py/ast_tree.py

@@ -3097,7 +3097,7 @@ def custom_notes(self, custom_functions: CustomFunctions = None):
                 lines = custom_functions.py_notes[self.py_name]
         return lines
 
-    def py_docstring(self, custom_functions: CustomFunctions, warning_command_dict: None) -> str:
+    def py_docstring(self, custom_functions: CustomFunctions, comment_command_dict: dict=None) -> str:
         """
         Python docstring of the command.
 
@@ -3107,21 +3107,20 @@ def py_docstring(self, custom_functions: CustomFunctions, warning_command_dict:
         custom_functions : CustomFunctions
             Custom functions object.
 
-        warning_command_dict: dict, optional
-            Dictionary of commands associated to a list of warnings.
+        comment_command_dict: dict, optional
+            Dictionary of commands associated to a list of comments with the
+            following format: ``{"command": [["message_type", "message"]}``.
             The default is ``None``.
-
-
         """
         xml_cmd = f"{self._terms['pn006p']} Command: `{self.name} <{self.url}>`_"
 
         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_, " " * 4)
-                items.extend([f"\n.. warning::\n\n{warning_}\n"])
+        if self.name in comment_command_dict.keys():
+            comments_ = comment_command_dict[self.name]
+            for (comment_type, comment_) in comments_:
+                comment_ = textwrap.indent(comment_, " " * 4)
+                items.extend([f"\n.. {comment_type}::\n\n{comment_}\n"])
 
         if self.default:
             if self.default.tag in item_needing_links_base_url:
@@ -3472,7 +3471,7 @@ def py_source(self, custom_functions=None, indent=""):
     def to_python(
         self,
         custom_functions=None,
-        warning_command_dict=None,
+        comment_command_dict=None,
         indent="",
         image_folder_path: Path = None,
     ):
@@ -3485,8 +3484,9 @@ def to_python(
             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.
+        comment_command_dict: dict, optional
+            Dictionary of commands associated to a list of comments with the
+            following format: ``{"command": [["message_type", "message"]}``.
             The default is ``None``.
 
         indent: str, optional
@@ -3503,7 +3503,7 @@ def to_python(
             IMAGE_FOLDER_PATH = image_folder_path
 
         docstr = textwrap.indent(
-            f'r"""{self.py_docstring(custom_functions, warning_command_dict)}\n"""',
+            f'r"""{self.py_docstring(custom_functions, comment_command_dict)}\n"""',
             prefix=indent + " " * 4,
         )
         if custom_functions is not None and self.py_name in custom_functions.lib_import:

src/pyconverter/xml2py/utils/utils.py

@@ -68,36 +68,42 @@ 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:
+def get_comment_command_dict(yaml_path: Path) -> dict:
     """
-    Get the list of commands that will raise a warning.
+    Get a dictionnary of messages to be added as warning, note, or info at the beginning of
+    a command documentation.
 
     Parameters
     ----------
     yaml_path: Path
         Path object of the YAML file.
-    """
-    warnings_ = get_config_data_value(yaml_path, "warnings")
-    if warnings_ is None:
-        logger.info("No warning commands found in the YAML file.")
-        return {}
-    warning_command_dict = {}
-    for warning_ in warnings_:
-        message = warning_["msg"]
-        commands = warning_["commands"]
-        for command in commands:
-            try:
-                warning_command_dict[command].append(message)
-            except KeyError:
-                warning_command_dict[command] = [message]
-
-    if warning_command_dict == {}:
-        logger.info("No warning commands found in the YAML file.")
-
-    else:
-        logger.info("Warning commands found in the YAML file.")
 
-    return warning_command_dict
+    Returns
+    -------
+    dict
+        Dictionary of comment to be added with the following format: ``{"command": [["message_type", "message"]}``.
+    """
+    beginning_comments = get_config_data_value(yaml_path, "beginning_comments")
+    if beginning_comments is None:
+        logger.info("No comments to be added found in the YAML file.")
+    comment_command_dict = {}
+    if beginning_comments:
+        for comment_ in beginning_comments:
+            message = comment_["msg"]
+            comment_type = comment_["type"]
+            if comment_type not in ["note", "warning", "info"]:
+                raise ValueError(f"Comment type '{comment_type}' not supported. Use 'note', 'warning', or 'info'.")
+            commands = comment_["commands"]
+            for command in commands:
+                try:
+                    comment_command_dict[command].append([comment_type, message])
+                except KeyError:
+                    comment_command_dict[command] = [[comment_type, message]]
+
+        if comment_command_dict == {}:
+            logger.info("No message found in the YAML file.")
+
+    return comment_command_dict
 
 
 def create_name_map(meta_command: list[str], yaml_file_path: Path) -> dict:

src/pyconverter/xml2py/writer.py

@@ -35,7 +35,7 @@
     create_name_map,
     get_config_data_value,
     get_refentry,
-    get_warning_command_dict,
+    get_comment_command_dict,
     import_handler,
 )
 import regex as re
@@ -432,7 +432,7 @@ def write_source(
 
     library_path = Path(get_library_path(new_package_path, config_path))
 
-    warning_command_dict = get_warning_command_dict(config_path)
+    comment_command_dict = get_comment_command_dict(config_path)
 
     if not library_path.is_dir():
         library_path.mkdir(parents=True, exist_ok=True)
@@ -444,7 +444,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, warning_command_dict, indent="")
+            python_method = command_obj.to_python(custom_functions, comment_command_dict, indent="")
             try:
                 exec(python_method)
                 with open(path, "w", encoding="utf-8") as fid:
@@ -488,7 +488,7 @@ def write_source(
             package_structure[module_name][file_name] = [class_name, class_structure]
             python_method = command.to_python(
                 custom_functions,
-                warning_command_dict,
+                comment_command_dict,
                 indent=4 * " ",
                 image_folder_path=image_folder_path,
             )