Link signature defaults for known objects to API locations.

When a default contains an instance, prefer to link to the **class** if available.
Most of the time if you link to an instance it's a dataclass default.

For the main TF API this mainly links simple defaults like enums, dtypes and activation functions back to their class pages.

For tensorflow_models this makes the pages for complex nested configs like [OptimizerConfig](https://github.com/tensorflow/models/blob/3d0e12fdd61f1e9e0515b5caed2a33635ae0c8c3/official/modeling/optimization/configs/optimization_config.py#L32) more useful by linking all the nested dataclass instance pages back to their class' page.

+ drop some TF1 special cases.

PiperOrigin-RevId: 436614177

Author: MarkDaoust

tools/tensorflow_docs/api_generator/reference_resolver.py

@@ -290,7 +290,7 @@ def one_ref(match):
 
     return '\n'.join(fixed_lines)
 
-  def python_link(self, link_text, ref_full_name):
+  def python_link(self, link_text: str, ref_full_name: Optional[str] = None):
     """Resolve a "`tf.symbol`" reference to a link.
 
     This will pick the canonical location for duplicate symbols.
@@ -302,6 +302,8 @@ def python_link(self, link_text, ref_full_name):
     Returns:
       A link to the documentation page of `ref_full_name`.
     """
+    if ref_full_name is None:
+      ref_full_name = link_text
     link_text = html.escape(link_text, quote=True)
 
     url = self.reference_to_url(ref_full_name)

tools/tensorflow_docs/api_generator/signature.py

@@ -25,7 +25,7 @@
 import textwrap
 import typing
 
-from typing import Any, Callable, Dict, List, Tuple, Type
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type
 
 import astor
 
@@ -131,14 +131,6 @@ def strip_obj_addresses(text):
 class FormatArguments(object):
   """Formats the arguments and adds type annotations if they exist."""
 
-  _INTERNAL_NAMES = {
-      'ops.GraphKeys': 'tf.GraphKeys',
-      '_ops.GraphKeys': 'tf.GraphKeys',
-      'init_ops.zeros_initializer': 'tf.zeros_initializer',
-      'init_ops.ones_initializer': 'tf.ones_initializer',
-      'saver_pb2.SaverDef': 'tf.train.SaverDef',
-  }
-
   # A regular expression capturing a python identifier.
   _IDENTIFIER_RE = r'[a-zA-Z_]\w*'
 
@@ -166,9 +158,11 @@ def __init__(
     self._reverse_index = parser_config.reverse_index
     self._reference_resolver = parser_config.reference_resolver
 
-  def get_link(self, obj_full_name: str) -> str:
+  def get_link(self,
+               link_text: str,
+               obj_full_name: Optional[str] = None) -> str:
     return self._reference_resolver.python_link(
-        link_text=obj_full_name, ref_full_name=obj_full_name)
+        link_text=link_text, ref_full_name=obj_full_name)
 
   def _extract_non_builtin_types(self, arg_obj: Any,
                                  non_builtin_types: List[Any]) -> List[Any]:
@@ -252,25 +246,54 @@ def _linkify(self, non_builtin_map: Dict[str, Any], match) -> str:
 
     return self.get_link(obj_full_name)
 
-  def preprocess(self, ast_typehint: str, obj_anno: Any) -> str:
+  def maybe_add_link(self, source: str, value: Any) -> str:
+    """Return a link to an object's api page if found.
+
+    Args:
+      source: The source string from the code.
+      value: The value of the object.
+
+    Returns:
+      The original string with maybe an HTML link added.
+    """
+    cls = type(value)
+
+    value_name = self._reverse_index.get(id(value), None)
+    cls_name = self._reverse_index.get(id(cls), None)
+
+    if cls_name is not None:
+      # It's much more common for the class to be documented than the instance.
+      # and the class page will provide better docs.
+      before = source.split('(')[0]
+      cls_short_name = cls_name.split('.')[-1]
+      if before.endswith(cls_short_name):
+        # Yes, this is a guess but it will usually be right.
+        return self.get_link(source, cls_name)
+
+    if value_name is not None:
+      return self.get_link(value_name, value_name)
+
+    return source
+
+  def preprocess(self, string: str, value: Any) -> str:
     """Links type annotations to its page if it exists.
 
     Args:
-      ast_typehint: AST extracted type annotation.
-      obj_anno: Type annotation object.
+      string: AST extracted type annotation.
+      value: Type annotation object.
 
     Returns:
       Linked type annotation if the type annotation object exists.
     """
     # If the object annotations exists in the reverse_index, get the link
     # directly for the entire annotation.
-    obj_anno_full_name = self._reverse_index.get(id(obj_anno), None)
+    obj_anno_full_name = self._reverse_index.get(id(value), None)
     if obj_anno_full_name is not None:
       return self.get_link(obj_anno_full_name)
 
-    non_builtin_ast_types = self._get_non_builtin_ast_types(ast_typehint)
+    non_builtin_ast_types = self._get_non_builtin_ast_types(string)
     try:
-      non_builtin_type_objs = self._extract_non_builtin_types(obj_anno, [])
+      non_builtin_type_objs = self._extract_non_builtin_types(value, [])
     except RecursionError:
       non_builtin_type_objs = {}
 
@@ -282,16 +305,7 @@ def preprocess(self, ast_typehint: str, obj_anno: Any) -> str:
       non_builtin_map = dict(zip(non_builtin_ast_types, non_builtin_type_objs))
 
     partial_func = functools.partial(self._linkify, non_builtin_map)
-    return self._INDIVIDUAL_TYPES_RE.sub(partial_func, ast_typehint)
-
-  def _replace_internal_names(self, default_text: str) -> str:
-    full_name_re = f'^{self._IDENTIFIER_RE}(.{self._IDENTIFIER_RE})+'
-    match = re.match(full_name_re, default_text)
-    if match:
-      for internal_name, public_name in self._INTERNAL_NAMES.items():
-        if match.group(0).startswith(internal_name):
-          return public_name + default_text[len(internal_name):]
-    return default_text
+    return self._INDIVIDUAL_TYPES_RE.sub(partial_func, string)
 
   def format_return(self, return_anno: Tuple[Any, str]) -> str:
     value, source = return_anno
@@ -339,21 +353,11 @@ def format_kwargs(self, kwargs: List[inspect.Parameter]) -> List[str]:
       default_text = None
       if kwarg.default is not EMPTY:
         default_val, default_source = kwarg.default
+        if default_source is None:
+          default_source = strip_obj_addresses(repr(default_val))
+        default_source = html.escape(default_source)
 
-        if id(default_val) in self._reverse_index:
-          default_text = self._reverse_index[id(default_val)]
-        elif default_source is not None:
-          default_text = default_source
-          if default_text != repr(default_val):
-            default_text = self._replace_internal_names(default_text)
-        # Kwarg without default value.
-        elif default_val is EMPTY:
-          kwargs_text_repr.extend(self.format_args([kwarg]))
-          continue
-        else:
-          # Strip object memory addresses to avoid unnecessary doc churn.
-          default_text = strip_obj_addresses(repr(default_val))
-        default_text = html.escape(str(default_text))
+        default_text = self.maybe_add_link(default_source, default_val)
 
       # Format the kwargs to add the type annotation and default values.
       typeanno = None

tools/tensorflow_docs/api_generator/signature_test.py

@@ -50,17 +50,29 @@ def setUp(self):
     super().setUp()
     self.known_object = object()
     reference_resolver = reference_resolver_lib.ReferenceResolver(
-        duplicate_of={},
+        link_prefix='/',
+        duplicate_of={
+            'tfdocs.api_generator.signature.extract_decorators':
+                'tfdocs.api_generator.signature.extract_decorators',
+            'location.of.object.in.api':
+                'location.of.object.in.api',
+        },
         is_fragment={
-            'tfdocs.api_generator.signature.extract_decorators': False
+            'location.of.object.in.api': False,
+            'tfdocs.api_generator.signature.extract_decorators': False,
         },
         py_module_names=[])
     self.parser_config = config.ParserConfig(
         reference_resolver=reference_resolver,
         duplicates={},
         duplicate_of={},
         tree={},
-        index={},
+        index={
+            'location.of.object.in.api':
+                self.known_object,
+            'tfdocs.api_generator.signature.extract_decorators':
+                signature.extract_decorators
+        },
         reverse_index={
             id(self.known_object):
                 'location.of.object.in.api',
@@ -79,7 +91,9 @@ def example_fun(arg=self.known_object):  # pylint: disable=unused-argument
         example_fun,
         parser_config=self.parser_config,
         func_type=signature.FuncType.FUNCTION)
-    self.assertEqual('(\n    arg=location.of.object.in.api\n)', str(sig))
+    self.assertEqual(
+        '(\n    arg=<a href="/location/of/object/in/api.md"><code>location.of.object.in.api</code></a>\n)',
+        str(sig))
 
   def test_literals(self):