Add warning tag support to documentation generator

Author: Foereaper

docs/ElunaDoc/parser.py

@@ -68,8 +68,8 @@ def __init__(self, name, data_type, description, default_value=None):
 
 class MethodDoc(object):
     """The documentation data of an Eluna method."""
-    @params(self=object, name=str, description=str, tables=[TableDict], prototypes=[str], parameters=[ParameterDoc], returned=[ParameterDoc])
-    def __init__(self, name, description, tables, prototypes, parameters, returned):
+    @params(self=object, name=str, description=str, tables=[TableDict], prototypes=[str], warning=[str], parameters=[ParameterDoc], returned=[ParameterDoc])
+    def __init__(self, name, description, tables, prototypes, warning, parameters, returned):
         self.name = name
         self.prototypes = prototypes
         self.tables = tables
@@ -110,6 +110,9 @@ def __init__(self, name, description, tables, prototypes, parameters, returned):
         self.short_description = self.description.split('</p>')[0][3:]
         # If it has a description, it is "documented".
         self.documented = self.description != ''
+        # Parse the warning as Markdown, but remote <p> tags
+        self.warning = markdown.markdown(warning)
+        self.warning = re.sub(r'^<p>(.*?)</p>$', r'\1', self.warning, flags=re.DOTALL)
 
     """Helper function to parse table dictionaries. Only used in Register methods for now."""
     def _format_dict_values(self, d):
@@ -171,6 +174,9 @@ class ClassParser(object):
     table_columns_regex = re.compile(r"\s*\*\s@columns\s*\[(.+)\]")
     table_values_regex = re.compile(r"\s*\*\s@values\s*\[(.+?)\]")
 
+    # Regex for catching warning tags
+    warning_regex = re.compile(r"""\s*\*\s*@warning\s+(.+)""", re.X)
+    
     param_regex = re.compile(r"""\s*\*\s@param\s        # The @param tag starts with opt. whitespace followed by "* @param ".
                                  ([^\s]+)\s(\w+)?       # The data type, a space, and the name of the param.
                                  (?:\s=\s([^\s:]+))?    # The default value: a space, =, and a value that can include periods but stops at whitespace or a colon.
@@ -207,6 +213,7 @@ def reset(self):
 
         # These are used to piece together the next `Method`.
         self.description = ''
+        self.warning = ''
         self.params = []
         self.returned = []
         self.method_name = None
@@ -253,6 +260,10 @@ def handle_table_values(self, match):
             # Append the processed values to the last table
             self.tables[-1]["values"].append(processed_values)
 
+    def handle_warning(self, match):
+        warning = match.group(1)
+        self.warning += warning
+
     def handle_param(self, match):
         data_type, name, default, description = match.group(1), match.group(2), match.group(3), match.group(4)
         self.params.append(ParameterDoc(name, data_type, description, default))
@@ -328,7 +339,7 @@ def make_prototype(parameters):
             # Format the method name into each prototype.
             self.prototypes = [proto.format(self.method_name) for proto in self.prototypes]
 
-        self.methods.append(MethodDoc(self.method_name, self.description, self.tables, self.prototypes, self.params, self.returned))
+        self.methods.append(MethodDoc(self.method_name, self.description, self.tables, self.prototypes, self.warning, self.params, self.returned))
 
     # Table of which handler is used to handle each regular expressions.
     regex_handlers = {
@@ -340,6 +351,7 @@ def make_prototype(parameters):
         table_regex: handle_table,
         table_columns_regex: handle_table_columns,
         table_values_regex: handle_table_values,
+        warning_regex: handle_warning,
         param_regex: handle_param,
         return_regex: handle_return,
         proto_regex: handle_proto,
@@ -354,13 +366,14 @@ def make_prototype(parameters):
         class_start_regex: [class_end_regex, class_body_regex],
         class_body_regex: [class_end_regex, class_body_regex],
         class_end_regex: [],
-        start_regex: [table_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
-        body_regex: [table_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
-        proto_regex: [table_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
-        table_regex: [table_regex, table_columns_regex, param_regex, return_regex, comment_end_regex, body_regex],
-        table_columns_regex: [table_values_regex, param_regex, return_regex, comment_end_regex, body_regex],
-        table_values_regex: [table_values_regex, table_regex, param_regex, return_regex, comment_end_regex, body_regex],
-        param_regex: [table_regex, param_regex, return_regex, comment_end_regex, body_regex],
+        start_regex: [table_regex, warning_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
+        body_regex: [table_regex, warning_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
+        proto_regex: [table_regex, warning_regex, param_regex, return_regex, proto_regex, comment_end_regex, body_regex],
+        table_regex: [table_regex, table_columns_regex, warning_regex, param_regex, return_regex, comment_end_regex, body_regex],
+        table_columns_regex: [table_values_regex, warning_regex, param_regex, return_regex, comment_end_regex, body_regex],
+        table_values_regex: [table_values_regex, table_regex, warning_regex, param_regex, return_regex, comment_end_regex, body_regex],
+        warning_regex: [table_values_regex, table_regex, warning_regex, param_regex, return_regex, comment_end_regex, body_regex],
+        param_regex: [table_regex, warning_regex, param_regex, return_regex, comment_end_regex, body_regex],
         return_regex: [return_regex, comment_end_regex],
         comment_end_regex: [end_regex],
         end_regex: [],

docs/ElunaDoc/templates/method.html

@@ -39,6 +39,11 @@ <h2>{{ current_class.name }} Methods</h2>
 
 
 {% block content %}
+    {%- if current_method.warning %}
+    <div style="border: 1px solid #f44336; background-color: #fdecea; color: #b71c1c; padding: 12px; border-radius: 4px; margin: 10px 0;">
+      <strong>Warning:</strong> {{ current_method.warning }}
+    </div>
+    {%- endif %}
     <div class='docblock'>
         {%- if current_method.documented %}
         {{ current_method.description|parse_links }}

methods/TrinityCore/GlobalMethods.h

@@ -1272,6 +1272,8 @@ namespace LuaGlobalFunctions
      *         until not Q:NextRow()
      *     end
      *
+     * @warning This method is flagged as **unsafe** and is **disabled by default**. Use with caution, or transition to Async queries.
+     * 
      * @param string sql : query to execute
      * @return [ElunaQuery] results or nil if no rows found or nil if no rows found
      */
@@ -1371,6 +1373,8 @@ namespace LuaGlobalFunctions
      *
      * For an example see [Global:WorldDBQuery].
      *
+     * @warning This method is flagged as **unsafe** and is **disabled by default**. Use with caution, or transition to Async queries.
+     * 
      * @param string sql : query to execute
      * @return [ElunaQuery] results or nil if no rows found
      */
@@ -1462,6 +1466,8 @@ namespace LuaGlobalFunctions
      *
      * For an example see [Global:WorldDBQuery].
      *
+     * @warning This method is flagged as **unsafe** and is **disabled by default**. Use with caution, or transition to Async queries.
+     * 
      * @param string sql : query to execute
      * @return [ElunaQuery] results or nil if no rows found
      */