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 = [