diff --git a/docfx_yaml/extension.py b/docfx_yaml/extension.py index bd116c7f..b3cc3a46 100644 --- a/docfx_yaml/extension.py +++ b/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"{uid}" \ if uid in hard_coded_references else \ f"{uid}" 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"): diff --git a/tests/test_helpers.py b/tests/test_helpers.py index 43d3420d..f3e1eb02 100644 --- a/tests/test_helpers.py +++ b/tests/test_helpers.py @@ -119,7 +119,7 @@ def test_extract_keyword(self): [ "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest", "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest" - ] + ], ] @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 = [