docs: enhance how references are generated (#5805)

* adjusted configurations

* enhancements to tool and configurations

* change reference in docs

* fixed issue in workflows reference

* added project name

* more optimizations

* fix context error

* added a types reference

* resolved missing types

* fix reference reflection types not having children

* add an expand url parameter

* added new option to the README

* added details about new option

docs-util/packages/utils/src/get-project-child.ts

@@ -4,28 +4,34 @@ import {
   ReflectionKind,
 } from "typedoc"
 
+const MAX_LEVEL = 3
+
 export function getProjectChild(
   project: ProjectReflection,
-  childName: string
+  childName: string,
+  level = 1
 ): DeclarationReflection | undefined {
   let reflection: DeclarationReflection | undefined = project.getChildByName(
     childName
   ) as DeclarationReflection
   const splitChildName = childName.split(".")
+  const canExpandFurther = level <= MAX_LEVEL
 
-  if (!reflection && splitChildName.length > 1) {
+  if (!reflection && splitChildName.length > 1 && canExpandFurther) {
     reflection = getProjectChild(
       project,
-      splitChildName[splitChildName.length - 1]
+      splitChildName[splitChildName.length - 1],
+      level + 1
     )
   }
 
   if (
     !reflection &&
     project.parent &&
-    project.parent instanceof ProjectReflection
+    project.parent instanceof ProjectReflection &&
+    canExpandFurther
   ) {
-    reflection = getProjectChild(project.parent, childName)
+    reflection = getProjectChild(project.parent, childName, level + 1)
   }
 
   if (!reflection) {

docs-util/packages/utils/src/get-type-children.ts

@@ -1,16 +1,23 @@
 import { DeclarationReflection, ProjectReflection, SomeType } from "typedoc"
 import { getProjectChild } from "./get-project-child"
 
+const MAX_LEVEL = 3
+
 export function getTypeChildren(
   reflectionType: SomeType,
-  project: ProjectReflection | undefined
+  project: ProjectReflection | undefined,
+  level = 1
 ): DeclarationReflection[] {
   let children: DeclarationReflection[] = []
 
+  if (level > MAX_LEVEL) {
+    return children
+  }
+
   switch (reflectionType.type) {
     case "intersection":
       reflectionType.types.forEach((intersectionType) => {
-        children.push(...getTypeChildren(intersectionType, project))
+        children.push(...getTypeChildren(intersectionType, project, level + 1))
       })
       break
     case "reference":
@@ -19,41 +26,48 @@ export function getTypeChildren(
         reflectionType.reflection && "children" in reflectionType.reflection
           ? reflectionType.reflection
           : project
-          ? getProjectChild(project, reflectionType.name)
-          : undefined
+            ? getProjectChild(project, reflectionType.name)
+            : undefined
 
       if (referencedReflection instanceof DeclarationReflection) {
         if (referencedReflection.children) {
           children = referencedReflection.children
-        } else if (reflectionType.typeArguments?.length) {
-          reflectionType.typeArguments.forEach((typeArgument, index) => {
-            if (reflectionType.name === "Omit" && index > 0) {
-              switch (typeArgument.type) {
-                case "literal":
-                  removeChild(typeArgument.value?.toString(), children)
-                  break
-                case "union":
-                  typeArgument.types.forEach((childItem) => {
-                    if (childItem.type === "literal") {
-                      removeChild(childItem.value?.toString(), children)
-                    } else {
-                      getTypeChildren(childItem, project).forEach((child) => {
-                        removeChild(child.name, children)
-                      })
-                    }
-                  })
-              }
-            } else {
-              const typeArgumentChildren = getTypeChildren(
-                typeArgument,
-                project
-              )
-              children.push(...typeArgumentChildren)
-            }
-          })
         } else if (referencedReflection.type) {
-          children = getTypeChildren(referencedReflection.type, project)
+          children = getTypeChildren(
+            referencedReflection.type,
+            project,
+            level + 1
+          )
         }
+      } else if (reflectionType.typeArguments?.length) {
+        reflectionType.typeArguments.forEach((typeArgument, index) => {
+          if (reflectionType.name === "Omit" && index > 0) {
+            switch (typeArgument.type) {
+              case "literal":
+                removeChild(typeArgument.value?.toString(), children)
+                break
+              case "union":
+                typeArgument.types.forEach((childItem) => {
+                  if (childItem.type === "literal") {
+                    removeChild(childItem.value?.toString(), children)
+                  } else {
+                    getTypeChildren(childItem, project, level + 1).forEach(
+                      (child) => {
+                        removeChild(child.name, children)
+                      }
+                    )
+                  }
+                })
+            }
+          } else {
+            const typeArgumentChildren = getTypeChildren(
+              typeArgument,
+              project,
+              level + 1
+            )
+            children.push(...typeArgumentChildren)
+          }
+        })
       }
       break
     case "reflection":
@@ -62,7 +76,7 @@ export function getTypeChildren(
       ]
       break
     case "array":
-      children = getTypeChildren(reflectionType.elementType, project)
+      children = getTypeChildren(reflectionType.elementType, project, level + 1)
   }
 
   return filterChildren(children)