fix: ignore cross reference conversion in examples (#332)

* fix: ignore cross reference conversion in examples

* test: update unit test

Author: dandhlee

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py

@@ -1395,7 +1395,14 @@ def find_uid_to_convert(
     return None
 
 
-def convert_cross_references(content: str, current_object_name: str, known_uids: List[str]) -> str:
+# TODO(https://github.com/googleapis/sphinx-docfx-yaml/issues/331): Improve
+# converting cross references for code content.
+def convert_cross_references(
+    content: str,
+    current_object_name: str,
+    known_uids: List[str],
+    ignore_examples: Optional[bool] = False,
+) -> str:
     """Finds and replaces references that should be a cross reference in given content.
 
     This should not convert any references that contain `current_object_name`,
@@ -1407,10 +1414,13 @@ def convert_cross_references(content: str, current_object_name: str, known_uids:
         content: body of content to parse and look for references in
         current_object_name: the name of the current Python object being processed
         known_uids: list of uid references to look for
+        ignore_examples: Don't convert references in example content
+            if set to True. False by default.
 
     Returns:
         content that has been modified with proper cross references if found.
     """
+    example_text = "Examples:"
     words = content.split(" ")
 
     # Contains a list of words that is not a valid reference or converted
@@ -1428,19 +1438,26 @@ def convert_cross_references(content: str, current_object_name: str, known_uids:
     }
     known_uids.extend(hard_coded_references.keys())
 
+    # Used to keep track of current position to avoid converting if needed.
+    example_index = len(content)
     for index, word in enumerate(words):
+        if ignore_examples and example_text in word:
+            example_index = index
         uid = find_uid_to_convert(
             word, words, index, known_uids, current_object_name, processed_words, hard_coded_references
         )
 
-        if uid:
+        # If the reference is found after example section, ignore it.
+        if uid and (
+            not ignore_examples or
+            (ignore_examples and index < example_index)
+        ):
             cross_reference = f"<a href=\"{hard_coded_references[uid]}\">{uid}</a>" \
                 if uid in hard_coded_references else \
                 f"<xref uid=\"{uid}\">{uid}</xref>"
 
             processed_words.append(word.replace(uid, cross_reference))
             print(f"Converted {uid} into cross reference in: \n{content}")
-
         else:
             # If cross reference has not been found, add current unchanged content.
             processed_words.append(word)
@@ -1452,7 +1469,12 @@ def convert_cross_references(content: str, current_object_name: str, known_uids:
 # For now, we inspect summary, syntax and attributes.
 def search_cross_references(obj, current_object_name: str, known_uids: List[str]):
     if obj.get("summary"):
-        obj["summary"] = convert_cross_references(obj["summary"], current_object_name, known_uids)
+        obj["summary"] = convert_cross_references(
+            obj["summary"],
+            current_object_name,
+            known_uids,
+            ignore_examples=True,
+        )
 
     if obj.get("syntax"):
         if obj["syntax"].get("parameters"):

packages/gcp-sphinx-docfx-yaml/tests/test_helpers.py

@@ -119,7 +119,7 @@ def test_extract_keyword(self):
         [
             "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest",
             "<a href=\"http://github.com/googleapis/python-grpc-google-iam-v1/blob/8e73b45993f030f521c0169b380d0fbafe66630b/google/iam/v1/iam_policy_pb2_grpc.py#L111-L118\">google.iam.v1.iam_policy_pb2.GetIamPolicyRequest</a>"
-        ]
+        ],
     ]
     @parameterized.expand(cross_references_testdata)
     def test_convert_cross_references(self, content, content_want):
@@ -133,6 +133,29 @@ def test_convert_cross_references(self, content, content_want):
         content_got = extension.convert_cross_references(content, current_object_name, keyword_map)
         self.assertEqual(content_got, content_want)
 
+    cross_references_test_data = [
+        [
+            """
+            Examples:
+              google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse: test content.
+            """,
+            """
+            Examples:
+              google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse: test content.
+            """,
+        ],
+    ]
+    @parameterized.expand(cross_references_testdata)
+    def test_does_not_convert_for_examples(self, content, content_want):
+        # Check that entries correctly turns into cross references.
+        keyword_map = [
+            "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse",
+            "google.cloud.bigquery_storage_v1.types.SplitResponse"
+        ]
+        current_object_name = "google.cloud.bigquery_storage_v1.types.SplitResponse"
+
+        content_got = extension.convert_cross_references(content, current_object_name, keyword_map, ignore_examples=True)
+        self.assertEqual(content_got, content_want)
 
     # Test data used to test for processing already-processed cross references.
     cross_references_short_testdata = [