fix: expand entry names in Overview page to be more descriptive (#159)

* fix: expand entry names to be more descriptive

* test: add unit test

docfx_yaml/extension.py

@@ -676,6 +676,19 @@ def _extract_docstring_info(summary_info, summary, name):
     return top_summary
 
 
+# Returns appropriate product name to display for given full name of entry.
+def extract_product_name(name):
+    if 'google.cloud' in name:
+        product_name = '.'.join(name.split('.')[2:])
+    elif 'google' in name:
+        product_name = '.'.join(name.split('.')[1:])
+    else:
+        # Use the short name for other formats.
+        product_name = name.split('.')[-1]
+
+    return product_name
+
+
 def _create_datam(app, cls, module, name, _type, obj, lines=None):
     """
     Build the data structure for an autodoc class
@@ -866,7 +879,8 @@ def _update_friendly_package_name(path):
 
     # If there is no summary, add a short snippet.
     else:
-        datam['summary'] = f"API documentation for `{short_name}` {_type}."
+        product_name = extract_product_name(name)
+        datam['summary'] = f"API documentation for `{product_name}` {_type}."
 
     if args or sig or summary_info:
         datam['syntax'] = {}
@@ -1432,7 +1446,8 @@ def convert_module_to_package_if_needed(obj):
         if 'source' in obj and 'path' in obj['source'] and obj['source']['path']:
             if obj['source']['path'].endswith(INITPY):
                 obj['type'] = 'subPackage'
-                obj['summary'] = "API documentation for `{}` package.".format(obj['name'])
+                product_name = extract_product_name(obj['fullName'])
+                obj['summary'] = f"API documentation for `{product_name}` package."
                 return
 
         for child_uid in obj['children']:

tests/test_helpers.py

@@ -3,6 +3,7 @@
 from docfx_yaml.extension import convert_cross_references
 from docfx_yaml.extension import search_cross_references
 from docfx_yaml.extension import format_code
+from docfx_yaml.extension import extract_product_name
 
 import unittest
 from parameterized import parameterized
@@ -169,5 +170,25 @@ def test_format_code(self):
         code_got = format_code(code)
         self.assertEqual(code_want, code_got)
 
+
+    def test_extract_product_name(self):
+        # Test to ensure different name formats extract product name properly.
+        name_want = "scheduler_v1.types.Digest"
+        name = "google.cloud.scheduler_v1.types.Digest"
+        product_name = extract_product_name(name)
+
+        self.assertEqual(name_want, product_name)
+
+        non_cloud_name = "google.scheduler_v1.types.Digest"
+        non_cloud_product_name = extract_product_name(non_cloud_name)
+
+        self.assertEqual(name_want, non_cloud_product_name)
+
+        short_name_want = "Digest"
+        short_name = "scheduler_v1.types.Digest"
+        short_product_name = extract_product_name(short_name)
+
+        self.assertEqual(short_name_want, short_product_name)
+
 if __name__ == '__main__':
     unittest.main()