DEV-2453: Admonitions Processing (#642)

Author: milldr

scripts/docs-collator/AbstractRenderer.py

@@ -39,6 +39,7 @@ def _post_rendering_fixes(self, repo, readme_md_file, submodule_dir=""):
             repo, content, submodule_dir
         )
         content = rendering.fix_mdx_format(content)
+        content = rendering.reformat_admonitions(content)
         io.save_string_to_file(readme_md_file, content)
 
     def _copy_extra_resources_for_docs(self, module_download_dir, module_docs_dir):

scripts/docs-collator/ComponentRenderer.py

@@ -65,6 +65,7 @@ def __render_doc(self, component, file):
         content = rendering.fix_self_non_closing_br_tags(content)
         content = rendering.fix_custom_non_self_closing_tags_in_pre(content)
         content = rendering.remove_logo_from_the_bottom(content)
+        content = rendering.reformat_admonitions(content)
         content = rendering.fix_mdx_format(content)
 
         change_log_file = os.path.join(os.path.dirname(file), CHANGELOG_MD)
@@ -73,6 +74,7 @@ def __render_doc(self, component, file):
             if os.path.exists(change_log_file)
             else ""
         )
+        change_log_content = rendering.reformat_admonitions(change_log_content)
         change_log_content = rendering.shift_headings(change_log_content)
 
         relative_path = os.path.relpath(file, module_download_dir)

scripts/docs-collator/ModuleRenderer.py

@@ -205,4 +205,5 @@ def __post_rendering_fixes_for_submodule(self, readme_md_file):
         content = rendering.fix_self_non_closing_br_tags(content)
         content = rendering.fix_custom_non_self_closing_tags_in_pre(content)
         content = rendering.fix_mdx_format(content)
+        content = rendering.reformat_admonitions(content)
         io.save_string_to_file(readme_md_file, content)

scripts/docs-collator/utils/rendering.py

@@ -257,3 +257,53 @@ def strip_frontmatter(content):
         frontmatter = []
 
     return "\n".join(content_lines), "\n".join(frontmatter)
+
+def reformat_admonitions(content):
+    """
+    Reformat admonitions to be compatible with Docusaurus.
+    """
+
+    admonition_map = {
+        "NOTE": "note",
+        "TIP": "tip",
+        "IMPORTANT": "important",
+        "WARNING": "warning",
+        "CAUTION": "danger",
+    }
+
+    # Split the content into lines for processing
+    lines = content.split('\n')
+    result = []  # Initialize a list to hold the result
+    in_admonition = False  # Flag to indicate if we're inside an admonition block
+    admonition_type = ""  # Variable to store the current admonition type
+
+    for line in lines:
+        # Check if the line marks the start of an admonition
+        admonition_start = re.match(r'> \[\!(TIP|WARNING|NOTE|IMPORTANT|CAUTION|DANGER)\]', line)
+
+        if admonition_start:
+            # Set the flag to indicate we're inside an admonition
+            in_admonition = True
+            # Get the type of admonition, convert to lowercase, and store it
+            original_admonition_type = admonition_start.group(1)
+            admonition_type = admonition_map.get(original_admonition_type, original_admonition_type.lower())
+            # Add the opening Docusaurus admonition tag with a newline
+            result.append(f":::{admonition_type}")
+            continue
+
+        if in_admonition:
+            # Process lines that are part of the admonition content
+            if line.startswith('>'):
+                # Remove the '>' prefix and add the line to the result
+                # (But keep the second '>' in the case of '> >' for nested blockquotes)
+                result.append(line[1:].strip())
+            else:
+                # Add the closing Docusaurus admonition tag and reset the flag
+                result.append("\n:::")
+                result.append(line)
+                in_admonition = False
+        else:
+            # Add lines outside admonition blocks as they are
+            result.append(line)
+
+    return '\n'.join(result)