From 36f29eee79b74ca7cc2111a04e9f90961d324576 Mon Sep 17 00:00:00 2001 From: mariosasko Date: Fri, 7 Oct 2022 13:47:32 +0200 Subject: [PATCH 1/3] Support links to parameters in text --- src/doc_builder/autodoc.py | 39 ++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/src/doc_builder/autodoc.py b/src/doc_builder/autodoc.py index 2f96c276..70ead0a5 100644 --- a/src/doc_builder/autodoc.py +++ b/src/doc_builder/autodoc.py @@ -533,36 +533,47 @@ def resolve_links_in_text(text, package, mapping, page_info): prefix = f"/docs/{package_name}/{version}/{language}/" def _resolve_link(search): - object_name, last_char = search.groups() + object_or_param_name, last_char = search.groups() # Deal with external libs first. - lib_name = object_name.split(".")[0] + lib_name = object_or_param_name.split(".")[0] if lib_name.startswith("~"): lib_name = lib_name[1:] if lib_name in HUGGINFACE_LIBS and lib_name != package_name: - link = get_external_object_link(object_name, page_info) + link = get_external_object_link(object_or_param_name, page_info) return f"{link}{last_char}" + object_name, param_name = None, None # If the name begins with `~`, we shortcut to the last part. - if object_name.startswith("~"): - obj = find_object_in_package(object_name[1:], package) - object_name = object_name.split(".")[-1] + if object_or_param_name.startswith("~"): + obj = find_object_in_package(object_or_param_name[1:], package) + object_name = object_or_param_name.split(".")[-1] + # If "#" is in the name, assume it's a link to the function/method parameter. + elif "#" in object_or_param_name: + obj = find_object_in_package(object_or_param_name.split("#", 1)[0], package) + param_name = object_or_param_name.split("#", 1)[-1] else: - obj = find_object_in_package(object_name, package) + obj = find_object_in_package(object_or_param_name, package) + object_name = object_or_param_name + # Object not found, return the original link text. if obj is None: - return f"`{object_name}`{last_char}" + return f"`{object_or_param_name}`{last_char}" - # If the object is not a class, we add () - if not isinstance(obj, (type, property)): - object_name = f"{object_name}()" + link_name = object_name if param_name is None else param_name + + # If the link points to an object and the object is not a class, we add () + if param_name is None and not isinstance(obj, (type, property)): + link_name = f"{link_name}()" # Link to the anchor anchor = get_shortest_path(obj, package) if anchor not in mapping: - return f"`{object_name}`{last_char}" + return f"`{link_name}`{last_char}" page = f"{prefix}{mapping[anchor]}" + if param_name: + anchor = f"{anchor}.{param_name}" if "#" in page: - return f"[{object_name}]({page}){last_char}" + return f"[{link_name}]({page}){last_char}" else: - return f"[{object_name}]({page}#{anchor}){last_char}" + return f"[{link_name}]({page}#{anchor}){last_char}" return re.sub(r"\[`([^`]+)`\]([^\(])", _resolve_link, text) From 601d0ab538fa5f5a7be3fc9ec2fbb103b264cb2a Mon Sep 17 00:00:00 2001 From: mariosasko Date: Fri, 7 Oct 2022 13:47:50 +0200 Subject: [PATCH 2/3] Test --- tests/test_autodoc.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 0d471f74..b033fdbe 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -371,6 +371,18 @@ def test_resolve_links_in_text(self): ), ) + self.assertEqual( + resolve_links_in_text( + "Link to [`transformers.BertModel.forward#input_ids`].", + transformers, + small_mapping, + page_info, + ), + ( + "Link to [input_ids](/docs/transformers/main/en/model_doc/bert.html#transformers.BertModel.forward.input_ids)." + ), + ) + self.assertEqual( resolve_links_in_text( "This is a regular [`link`](url)", From 0d8ce9cb5fc8d5a16abe7f75446f4b17f943bfc2 Mon Sep 17 00:00:00 2001 From: mariosasko Date: Fri, 7 Oct 2022 16:30:57 +0200 Subject: [PATCH 3/3] Address comments --- src/doc_builder/autodoc.py | 15 ++++++++++----- tests/test_autodoc.py | 4 ++-- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/src/doc_builder/autodoc.py b/src/doc_builder/autodoc.py index 70ead0a5..f2e67ee4 100644 --- a/src/doc_builder/autodoc.py +++ b/src/doc_builder/autodoc.py @@ -542,14 +542,19 @@ def _resolve_link(search): link = get_external_object_link(object_or_param_name, page_info) return f"{link}{last_char}" object_name, param_name = None, None + # If `#` is in the name, assume it's a link to the function/method parameter. + if "#" in object_or_param_name: + object_name_for_param = object_or_param_name.split("#", 1)[0] + # Strip preceding `~` if it's there. + object_name_for_param = ( + object_name_for_param[1:] if object_name_for_param.startswith("~") else object_name_for_param + ) + obj = find_object_in_package(object_name_for_param, package) + param_name = object_or_param_name.split("#", 1)[-1] # If the name begins with `~`, we shortcut to the last part. - if object_or_param_name.startswith("~"): + elif object_or_param_name.startswith("~"): obj = find_object_in_package(object_or_param_name[1:], package) object_name = object_or_param_name.split(".")[-1] - # If "#" is in the name, assume it's a link to the function/method parameter. - elif "#" in object_or_param_name: - obj = find_object_in_package(object_or_param_name.split("#", 1)[0], package) - param_name = object_or_param_name.split("#", 1)[-1] else: obj = find_object_in_package(object_or_param_name, package) object_name = object_or_param_name diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index b033fdbe..c1925158 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -373,13 +373,13 @@ def test_resolve_links_in_text(self): self.assertEqual( resolve_links_in_text( - "Link to [`transformers.BertModel.forward#input_ids`].", + "Link to [`transformers.BertModel.forward#input_ids`], [`~transformers.BertModel.forward#input_ids`].", transformers, small_mapping, page_info, ), ( - "Link to [input_ids](/docs/transformers/main/en/model_doc/bert.html#transformers.BertModel.forward.input_ids)." + "Link to [input_ids](/docs/transformers/main/en/model_doc/bert.html#transformers.BertModel.forward.input_ids), [input_ids](/docs/transformers/main/en/model_doc/bert.html#transformers.BertModel.forward.input_ids)." ), )