feat: clarify names in the left nav (#16)

* feat: clarify names in the left nav

* fix: improve disambiguation and parsing names

docfx_yaml/extension.py

@@ -21,6 +21,7 @@
 import os
 import inspect
 import re
+import copy
 from functools import partial
 from itertools import zip_longest
 
@@ -562,17 +563,42 @@ def build_finished(app, exception):
     """
     Output YAML on the file system.
     """
+
+    # Used to get rid of the uidname field for cleaner toc file.
+    def sanitize_uidname_field(toc_yaml):
+        for module in toc_yaml:
+            if 'items' in module:
+                sanitize_uidname_field(module['items'])
+            module.pop('uidname')
+
+    # Parses the package name and returns package name and module name.
+    def find_package_name(package_name):
+        for name in package_name:
+            if name != "google" and name != "cloud":
+                return [name, package_name[-1]]
+
+    # Used to disambiguate names that have same entries.
+    def disambiguate_toc_name(toc_yaml):
+        names = {}
+        for module in toc_yaml:
+            names[module['name']] = 1 if module['name'] not in names else 2
+            if 'items' in module:
+                disambiguate_toc_name(module['items'])
+
+        for module in toc_yaml:
+            if names[module['name']] > 1:
+                module['name'] = ".".join(find_package_name(module['uidname'].split(".")))
+
     def find_node_in_toc_tree(toc_yaml, to_add_node):
         for module in toc_yaml:
-            if module['name'] == to_add_node:
+            if module['uidname'] == to_add_node:
                 return module
 
             if 'items' in module:
                 items = module['items']
                 found_module = find_node_in_toc_tree(items, to_add_node)
                 if found_module != None:
                     return found_module
-
         return None
 
     def convert_module_to_package_if_needed(obj):
@@ -756,6 +782,13 @@ def convert_module_to_package_if_needed(obj):
                     raise ValueError("Unable to dump object\n{0}".format(yaml_data)) from e
 
             file_name_set.add(filename)
+
+            # Parse the name of the object.
+            # Some types will need additional parsing to de-duplicate their names and contain
+            # a portion of their parent name for better disambiguation. This is done in 
+            # disambiguate_toc_name
+
+            node_name = obj.get('class').split(".")[-1] if obj.get('class') else obj['name']
 
             # Build nested TOC
             if uid.count('.') >= 1:
@@ -764,16 +797,40 @@ def convert_module_to_package_if_needed(obj):
 
                 if found_node:
                     found_node.pop('uid', 'No uid found')
-                    found_node.setdefault('items', [{'name': 'Overview', 'uid': parent_level}]).append({'name': uid, 'uid': uid})
+                    found_node.setdefault(
+                      'items', 
+                      [{'name': 'Overview', 'uidname': parent_level, 'uid': parent_level}]
+                    ).append({
+                      'name': node_name,
+                      'uidname': uid, 
+                      'uid': uid
+                    })
                 else:
-                    toc_yaml.append({'name': uid, 'uid': uid})
+                    toc_yaml.append({
+                      'name': node_name, 
+                      'uidname': uid, 
+                      'uid': uid
+                    })
 
             else:
-                toc_yaml.append({'name': uid, 'uid': uid})
+                toc_yaml.append({
+                  'name': node_name, 
+                  'uidname': uid, 
+                  'uid': uid
+                })
 
     if len(toc_yaml) == 0:
         raise RuntimeError("No documentation for this module.")
 
+    # Perform additional disambiguation of the name
+    disambiguate_toc_name(toc_yaml)
+
+    # Keeping uidname field carrys over onto the toc.yaml files, we need to
+    # be keep using them but don't need them in the actual file
+    toc_yaml_with_uid = copy.deepcopy(toc_yaml)
+
+    sanitize_uidname_field(toc_yaml)
+
     toc_file = os.path.join(normalized_outdir, 'toc.yml')
     with open(toc_file, 'w') as writable:
         writable.write(
@@ -789,12 +846,12 @@ def convert_module_to_package_if_needed(obj):
     index_file = os.path.join(normalized_outdir, 'index.yml')
     index_children = []
     index_references = []
-    for item in toc_yaml:
-        index_children.append(item.get('name', ''))
+    for item in toc_yaml_with_uid:
+        index_children.append(item.get('uidname', ''))
         index_references.append({
-            'uid': item.get('name', ''),
+            'uid': item.get('uidname', ''),
             'name': item.get('name', ''),
-            'fullname': item.get('name', ''),
+            'fullname': item.get('uidname', ''),
             'isExternal': False
         })
     with open(index_file, 'w') as index_file_obj: