Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: ignore cross reference conversion in examples #332

Merged
merged 2 commits into from
Nov 1, 2023
Merged

fix: ignore cross reference conversion in examples #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39e7400
fix: ignore cross reference conversion in examples
dandhlee Oct 31, 2023
cc296d8
test: update unit test
dandhlee Oct 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 26 additions & 4 deletions docfx_yaml/extension.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand All @@ -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
Expand All @@ -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)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, as long as there cannot be content after the example.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Examples: is only used by the bigframes team and it's their last content in the summary.

):
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)
Expand All @@ -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"):
Expand Down
25 changes: 24 additions & 1 deletion tests/test_helpers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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 = [
Expand Down