Add wiring for self-links in generated docs.

PiperOrigin-RevId: 515056793

Author: swegner

tools/tensorflow_docs/api_generator/config.py

@@ -17,9 +17,21 @@
 class ParserConfig(object):
   """Stores all indexes required to parse the docs."""
 
-  def __init__(self, *, reference_resolver, duplicates, duplicate_of, tree,
-               index, reverse_index, path_tree, api_tree, base_dir,
-               code_url_prefix):
+  def __init__(
+      self,
+      *,
+      reference_resolver,
+      duplicates,
+      duplicate_of,
+      tree,
+      index,
+      reverse_index,
+      path_tree,
+      api_tree,
+      base_dir,
+      code_url_prefix,
+      self_link_base
+  ):
     """Object with the common config for docs_for_object() calls.
 
     Args:
@@ -38,6 +50,8 @@ def __init__(self, *, reference_resolver, duplicates, duplicate_of, tree,
       base_dir: A base path that is stripped from file locations written to the
         docs.
       code_url_prefix: A Url to pre-pend to the links to file locations.
+      self_link_base: A Url to pre-pend to self-links to the generated docs
+        pages.
     """
     self.reference_resolver = reference_resolver
     self.duplicates = duplicates
@@ -49,6 +63,7 @@ def __init__(self, *, reference_resolver, duplicates, duplicate_of, tree,
     self.api_tree = api_tree
     self.base_dir = base_dir
     self.code_url_prefix = code_url_prefix
+    self.self_link_base = self_link_base
 
   def py_name_to_object(self, full_name):
     """Return the Python object for a Python symbol name."""

tools/tensorflow_docs/api_generator/generate_lib.py

@@ -97,7 +97,7 @@ def write_docs(
       attribute. For some classes (list, tuple, etc) __doc__ is not writable.
       Pass those docs like: `extra_docs={id(obj): "docs"}`
     page_builder_classes: A optional dict of `{ObjectType:Type[PageInfo]}` for
-        overriding the default page builder classes.
+      overriding the default page builder classes.
 
   Raises:
     ValueError: if `output_dir` is not an absolute path
@@ -168,12 +168,13 @@ def write_docs(
   if api_report is not None:
     api_report.write(output_dir / root_module_name / 'api_report.pb')
 
-
   if num_docs_output <= 1:
-    raise ValueError('The `DocGenerator` failed to generate any docs. Verify '
-                     'your arguments (`base_dir` and `callbacks`). '
-                     'Everything you want documented should be within '
-                     '`base_dir`.')
+    raise ValueError(
+        'The `DocGenerator` failed to generate any docs. Verify '
+        'your arguments (`base_dir` and `callbacks`). '
+        'Everything you want documented should be within '
+        '`base_dir`.'
+    )
 
   if yaml_toc:
     if isinstance(yaml_toc, bool):
@@ -286,15 +287,18 @@ class DocGenerator:
 
   def __init__(
       self,
+      *,
       root_title: str,
       py_modules: Sequence[Tuple[str, Any]],
       base_dir: Optional[Sequence[Union[str, pathlib.Path]]] = None,
       code_url_prefix: Union[Optional[str], Sequence[Optional[str]]] = (),
+      self_link_base: Optional[str] = None,
       search_hints: bool = True,
       site_path: str = 'api_docs/python',
       private_map: Optional[Dict[str, str]] = None,
       visitor_cls: Type[doc_generator_visitor.DocGeneratorVisitor] = (
-          doc_generator_visitor.DocGeneratorVisitor),
+          doc_generator_visitor.DocGeneratorVisitor
+      ),
       api_cache: bool = True,
       callbacks: Optional[List[public_api.ApiFilter]] = None,
       yaml_toc: Union[bool, Type[toc_lib.TocBuilder]] = True,
@@ -315,12 +319,15 @@ def __init__(
         in" paths. These are zipped with `base-dir`, to set the `defined_in`
         path for each file. The defined in link for `{base_dir}/path/to/file` is
         set to `{code_url_prefix}/path/to/file`.
+      self_link_base: A string. A URL prefix pre-pend to self-links to the
+        generated docs pages. Optional, if no `self_link_base` is supplied, no
+        self-link will be added.
       search_hints: Bool. Include metadata search hints at the top of each file.
       site_path: Path prefix in the "_toc.yaml"
       private_map: DEPRECATED. Use `api_generator.doc_controls`, or pass a
-        filter to the `callbacks` argument. A
-        `{"module.path.to.object": ["names"]}` dictionary. Specific
-        aliases that should not be shown in the resulting docs.
+        filter to the `callbacks` argument. A `{"module.path.to.object":
+        ["names"]}` dictionary. Specific aliases that should not be shown in the
+        resulting docs.
       visitor_cls: An option to override the default visitor class
         `doc_generator_visitor.DocGeneratorVisitor`.
       api_cache: Bool. Generate an api_cache file. This is used to easily add
@@ -364,10 +371,13 @@ def __init__(
       raise ValueError('`code_url_prefix` cannot be empty')
 
     if len(self._code_url_prefix) != len(base_dir):
-      raise ValueError('The `base_dir` list should have the same number of '
-                       'elements as the `code_url_prefix` list (they get '
-                       'zipped together).')
+      raise ValueError(
+          'The `base_dir` list should have the same number of '
+          'elements as the `code_url_prefix` list (they get '
+          'zipped together).'
+      )
 
+    self._self_link_base = self_link_base
     self._search_hints = search_hints
     self._site_path = site_path
     self._private_map = private_map or {}
@@ -399,7 +409,9 @@ def make_parser_config(self,
         path_tree=visitor.path_tree,
         api_tree=visitor.api_tree,
         base_dir=self._base_dir,
-        code_url_prefix=self._code_url_prefix)
+        code_url_prefix=self._code_url_prefix,
+        self_link_base=self._self_link_base,
+    )
 
   def run_extraction(self):
     """Walks the module contents, returns an index of all visited objects.

tools/tensorflow_docs/api_generator/pretty_docs/base_page.py

@@ -205,6 +205,14 @@ def set_defined_in(self, defined_in):
     assert self.defined_in is None
     self._defined_in = defined_in
 
+  @property
+  def self_link(self):
+    if not self.parser_config.self_link_base:
+      return None
+    rel_path = parser.documentation_path(self.full_name)
+    rel_path = rel_path[: -1 * len('.md')]  # strip suffix
+    return f'{self.parser_config.self_link_base}/{rel_path}'
+
   @property
   def aliases(self):
     """Returns a list of all full names for the documented object."""