From 5c9a10a895f9b9b8a6d120f6bfd7932af4ad77d2 Mon Sep 17 00:00:00 2001
From: ohmayr <omairn@google.com>
Date: Wed, 28 Jan 2026 22:21:13 +0000
Subject: [PATCH 1/4] chore: cache pandoc rst conversion

---
 gapic/utils/rst.py | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/gapic/utils/rst.py b/gapic/utils/rst.py
index dd1d65d75d..9956b6d9b0 100644
--- a/gapic/utils/rst.py
+++ b/gapic/utils/rst.py
@@ -17,8 +17,23 @@
 
 import pypandoc  # type: ignore
 
+import functools
+
 from gapic.utils.lines import wrap
 
+@functools.lru_cache(maxsize=2048)
+def _convert_pandoc(text: str, columns: int, source_format: str) -> str:
+    """Cached helper to run pypandoc with specific column width.
+    
+    Args:
+        columns: Must be positive. Enforced by caller.
+    """
+    return pypandoc.convert_text(text, 'rst',
+        format=source_format,
+        extra_args=['--columns=%d' % columns],
+    ).strip()
+
+
 
 def rst(
     text: str,
@@ -56,17 +71,11 @@ def rst(
         )
     else:
         # Convert from CommonMark to ReStructured Text.
-        answer = (
-            pypandoc.convert_text(
-                text,
-                "rst",
-                format=source_format,
-                verify_format=False,
-                extra_args=["--columns=%d" % (width - indent)],
-            )
-            .strip()
-            .replace("\n", f"\n{' ' * indent}")
-        )
+        answer = _convert_pandoc(
+            str(text), 
+            width - indent, 
+            str(source_format)
+        ).replace('\n', f"\n{' ' * indent}")
 
     # Add a newline to the end of the document if any line breaks are
     # already present.

From 6af16c1529e4a78a5475c848d591f974edd49cc2 Mon Sep 17 00:00:00 2001
From: ohmayr <omairn@google.com>
Date: Thu, 29 Jan 2026 01:03:54 +0000
Subject: [PATCH 2/4] wip

---
 gapic/utils/rst.py           | 5 +++--
 tests/unit/utils/test_rst.py | 8 ++++++++
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/gapic/utils/rst.py b/gapic/utils/rst.py
index 9956b6d9b0..828902098b 100644
--- a/gapic/utils/rst.py
+++ b/gapic/utils/rst.py
@@ -21,7 +21,7 @@
 
 from gapic.utils.lines import wrap
 
-@functools.lru_cache(maxsize=2048)
+@functools.lru_cache(maxsize=None)
 def _convert_pandoc(text: str, columns: int, source_format: str) -> str:
     """Cached helper to run pypandoc with specific column width.
     
@@ -31,6 +31,7 @@ def _convert_pandoc(text: str, columns: int, source_format: str) -> str:
     return pypandoc.convert_text(text, 'rst',
         format=source_format,
         extra_args=['--columns=%d' % columns],
+        verify_format=False,
     ).strip()
 
 
@@ -62,7 +63,7 @@ def rst(
     # do not convert it.
     # (This makes code generation significantly faster; calling out to pandoc
     # is by far the most expensive thing we do.)
-    if not re.search(r"[|*`_[\]]", text):
+    if not re.search(r"(?<!\w)_|_(?!\w)|[|*`\[\]]", text):
         answer = wrap(
             text,
             indent=indent,
diff --git a/tests/unit/utils/test_rst.py b/tests/unit/utils/test_rst.py
index 08c42a35b9..c4e64461f4 100644
--- a/tests/unit/utils/test_rst.py
+++ b/tests/unit/utils/test_rst.py
@@ -32,6 +32,14 @@ def test_rst_formatted():
         assert convert_text.call_count == 1
         assert convert_text.mock_calls[0][1][1] == "rst"
         assert convert_text.mock_calls[0][2]["format"] == "commonmark"
+        assert convert_text.mock_calls[0][2]["verify_format"] is False
+
+
+def test_rst_snake_case():
+    with mock.patch.object(pypandoc, "convert_text") as convert_text:
+        s = "some_variable_name"
+        assert utils.rst(s) == s
+        assert convert_text.call_count == 0
 
 
 def test_rst_add_newline():

From 9b48d93d7b04c8d9bd4d13e1967ec0e6f062a7ee Mon Sep 17 00:00:00 2001
From: ohmayr <omairn@google.com>
Date: Thu, 29 Jan 2026 21:57:55 +0000
Subject: [PATCH 3/4] wip

---
 gapic/utils/rst.py | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/gapic/utils/rst.py b/gapic/utils/rst.py
index 828902098b..d1eec2e87a 100644
--- a/gapic/utils/rst.py
+++ b/gapic/utils/rst.py
@@ -63,7 +63,7 @@ def rst(
     # do not convert it.
     # (This makes code generation significantly faster; calling out to pandoc
     # is by far the most expensive thing we do.)
-    if not re.search(r"(?<!\w)_|_(?!\w)|[|*`\[\]]", text):
+    if not re.search(r"[|*`_[\]]", text):
         answer = wrap(
             text,
             indent=indent,
@@ -71,12 +71,29 @@ def rst(
             width=width - indent,
         )
     else:
-        # Convert from CommonMark to ReStructured Text.
-        answer = _convert_pandoc(
-            str(text), 
-            width - indent, 
-            str(source_format)
-        ).replace('\n', f"\n{' ' * indent}")
+        # Check if snake_case-only AND NOT a list.
+        # This regex excludes underscores surrounded by word characters, meaning it finds "real" formatting.
+        has_real_formatting = re.search(r"(?<!\w)_|_(?!\w)|[|*`\[\]]", text)
+        is_list = re.search(r"^\s*([-+*]|\d+\.)\s+", text, re.MULTILINE)
+
+        if not has_real_formatting and not is_list:
+            # Mimic Pandoc behavior for plain text with snake_case:
+            # 1. Collapse multiple spaces (Markdown behavior)
+            text_normalized = re.sub(r'[ \t]+', ' ', text)
+            # 2. Wrap without the specific 'docstring first line' offset
+            answer = wrap(
+                text_normalized,
+                indent=indent,
+                offset=0,
+                width=width - indent,
+            )
+        else:
+            # Convert from CommonMark to ReStructured Text.
+            answer = _convert_pandoc(
+                str(text), 
+                width - indent, 
+                str(source_format)
+            ).replace('\n', f"\n{' ' * indent}")
 
     # Add a newline to the end of the document if any line breaks are
     # already present.

From e5efb6190502b666c43f7a82fe119f75ff9d1fbe Mon Sep 17 00:00:00 2001
From: ohmayr <omairn@google.com>
Date: Thu, 29 Jan 2026 23:30:02 +0000
Subject: [PATCH 4/4] wip

---
 gapic/utils/rst.py | 46 ++++++++++------------------------------------
 1 file changed, 10 insertions(+), 36 deletions(-)

diff --git a/gapic/utils/rst.py b/gapic/utils/rst.py
index d1eec2e87a..0cac3e09f2 100644
--- a/gapic/utils/rst.py
+++ b/gapic/utils/rst.py
@@ -17,23 +17,14 @@
 
 import pypandoc  # type: ignore
 
-import functools
-
 from gapic.utils.lines import wrap
 
-@functools.lru_cache(maxsize=None)
-def _convert_pandoc(text: str, columns: int, source_format: str) -> str:
-    """Cached helper to run pypandoc with specific column width.
-    
-    Args:
-        columns: Must be positive. Enforced by caller.
-    """
-    return pypandoc.convert_text(text, 'rst',
-        format=source_format,
-        extra_args=['--columns=%d' % columns],
-        verify_format=False,
-    ).strip()
 
+import functools
+
+@functools.lru_cache(maxsize=None)
+def _p(t, c, f):
+    return pypandoc.convert_text(t, "rst", format=f, verify_format=False, extra_args=["--columns=%d" % c]).strip()
 
 
 def rst(
@@ -71,29 +62,12 @@ def rst(
             width=width - indent,
         )
     else:
-        # Check if snake_case-only AND NOT a list.
-        # This regex excludes underscores surrounded by word characters, meaning it finds "real" formatting.
-        has_real_formatting = re.search(r"(?<!\w)_|_(?!\w)|[|*`\[\]]", text)
-        is_list = re.search(r"^\s*([-+*]|\d+\.)\s+", text, re.MULTILINE)
-
-        if not has_real_formatting and not is_list:
-            # Mimic Pandoc behavior for plain text with snake_case:
-            # 1. Collapse multiple spaces (Markdown behavior)
-            text_normalized = re.sub(r'[ \t]+', ' ', text)
-            # 2. Wrap without the specific 'docstring first line' offset
-            answer = wrap(
-                text_normalized,
-                indent=indent,
-                offset=0,
-                width=width - indent,
-            )
+        # Fast path for snake_case and other simple symbols
+        if not re.search(r"[*`]|(?<!\w)_|_(?!\w)|\[.*\]\s*[(\[]|^\||^\s*([-+*]|\d+\.)\s+", text, re.M):
+            answer = wrap(re.sub(r"[ \t]+", " ", text).replace("|", "\\|"), indent=indent, width=width - indent)
         else:
-            # Convert from CommonMark to ReStructured Text.
-            answer = _convert_pandoc(
-                str(text), 
-                width - indent, 
-                str(source_format)
-            ).replace('\n', f"\n{' ' * indent}")
+            # Convert from CommonMark to ReStructured Text (cached).
+            answer = _p(str(text), width - indent, str(source_format)).replace("\n", f"\n{' ' * indent}")
 
     # Add a newline to the end of the document if any line breaks are
     # already present.