docs: ng19 typedoc fixes

SAP · Dec 29, 2024 · c752ea3 · c752ea3
1 parent d5ed28f
commit c752ea3
Show file tree

Hide file tree

Showing 19 changed files with 1,362 additions and 766 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -212,7 +212,6 @@
                         "types": "prefer-import"
                     }
                 ],
-                "@typescript-eslint/type-annotation-spacing": "error",
                 "@typescript-eslint/unified-signatures": "error",
                 "arrow-body-style": "error",
                 "arrow-parens": ["off", "always"],

diff --git a/libs/core/project.json b/libs/core/project.json
@@ -12,7 +12,8 @@
         "compile-typedoc": {
             "executor": "@fundamental-ngx/nx-plugin:compile-typedoc",
             "options": {
-                "outputPath": "libs/docs/typedoc/core"
+                "outputPath": "libs/docs/typedoc/core",
+                "tsConfig": "libs/core/tsconfig.typedoc.json"
             },
             "outputs": ["{options.outputPath}"]
         },

diff --git a/libs/core/tsconfig.json b/libs/core/tsconfig.json
@@ -3,6 +3,9 @@
     "files": [],
     "include": [],
     "references": [
+        {
+            "path": "./tsconfig.typedoc.json"
+        },
         {
             "path": "./tsconfig.lib.json"
         },

diff --git a/libs/core/tsconfig.typedoc.json b/libs/core/tsconfig.typedoc.json
@@ -0,0 +1,21 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../dist/out-tsc",
+        "target": "ES2022",
+        "declaration": true,
+        "declarationMap": true,
+        "types": [],
+        "lib": ["dom", "es2018"],
+        "useDefineForClassFields": false,
+        "jsx": "react",
+        "jsxFactory": "JSX.createElement",
+        "jsxFragmentFactory": "JSX.Fragment"
+    },
+    "angularCompilerOptions": {
+        "skipTemplateCodegen": true,
+        "strictMetadataEmit": true,
+        "enableResourceInlining": true
+    },
+    "files": ["./index.ts"]
+}
diff --git a/libs/cx/project.json b/libs/cx/project.json
@@ -12,7 +12,8 @@
         "compile-typedoc": {
             "executor": "@fundamental-ngx/nx-plugin:compile-typedoc",
             "options": {
-                "outputPath": "libs/docs/typedoc/cx"
+                "outputPath": "libs/docs/typedoc/cx",
+                "tsConfig": "libs/cx/tsconfig.typedoc.json"
             },
             "outputs": ["{options.outputPath}"]
         },

diff --git a/libs/cx/tsconfig.json b/libs/cx/tsconfig.json
@@ -3,6 +3,9 @@
     "files": [],
     "include": [],
     "references": [
+        {
+            "path": "./tsconfig.typedoc.json"
+        },
         {
             "path": "./tsconfig.lib.json"
         },

diff --git a/libs/cx/tsconfig.typedoc.json b/libs/cx/tsconfig.typedoc.json
@@ -0,0 +1,21 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../dist/out-tsc",
+        "target": "ES2022",
+        "declaration": true,
+        "declarationMap": true,
+        "types": [],
+        "lib": ["dom", "es2018"],
+        "useDefineForClassFields": false,
+        "jsx": "react",
+        "jsxFactory": "JSX.createElement",
+        "jsxFragmentFactory": "JSX.Fragment"
+    },
+    "angularCompilerOptions": {
+        "skipTemplateCodegen": true,
+        "strictMetadataEmit": true,
+        "enableResourceInlining": true
+    },
+    "files": ["./index.ts"]
+}
diff --git a/libs/nx-plugin/src/executors/compile-typedoc/executor.ts b/libs/nx-plugin/src/executors/compile-typedoc/executor.ts
@@ -25,7 +25,9 @@ export default async function compileTypedocs(_options: CompileTypedocExecutorSc
         },
         context
     );
-    const { tsConfig } = readTargetOptions({ project: context.projectName as string, target: 'build' }, context);
+    const tsConfig: string =
+        _options.tsConfig ||
+        readTargetOptions({ project: context.projectName as string, target: 'build' }, context).tsConfig;
     const ngPackageJsonFiles = fastGlobSync(projectPath + '/**/*/ng-package.json');
     const entryPoints = ngPackageJsonFiles.map((f) => {
         const json = JSON.parse(readFileSync(f, 'utf-8'));
@@ -44,11 +46,6 @@ export default async function compileTypedocs(_options: CompileTypedocExecutorSc
         plugin: ['typedoc-plugin-merge-modules'],
         mergeModulesRenameDefaults: true,
         mergeModulesMergeMode: 'project',
-        compilerOptions: {
-            jsx: 'react',
-            jsxFactory: 'JSX.createElement',
-            jsxFragmentFactory: 'JSX.Fragment'
-        },
         theme: 'fd-typedoc'
     } as unknown as Partial<TypeDocOptions>);
     app.options.addReader(new TSConfigReader());

diff --git a/libs/nx-plugin/src/executors/compile-typedoc/schema.d.ts b/libs/nx-plugin/src/executors/compile-typedoc/schema.d.ts
@@ -1,3 +1,4 @@
 export interface CompileTypedocExecutorSchema {
     outputPath: string;
+    tsConfig?: string;
 }
diff --git a/libs/nx-plugin/src/executors/compile-typedoc/schema.json b/libs/nx-plugin/src/executors/compile-typedoc/schema.json
@@ -8,6 +8,10 @@
         "outputPath": {
             "type": "string",
             "description": "Path to the output directory"
+        },
+        "tsConfig": {
+            "type": "string",
+            "description": "Path to the tsconfig file. If not provided, the executor will pick the 'build' target's tsConfig"
         }
     },
     "required": []

diff --git a/libs/nx-plugin/src/executors/compile-typedoc/theme/index.tsx b/libs/nx-plugin/src/executors/compile-typedoc/theme/index.tsx
@@ -3,13 +3,12 @@ import {
     DeclarationHierarchy,
     DeclarationReflection,
     DefaultThemeRenderContext,
-    DocumentReflection,
     JSX,
     PageEvent,
     Reflection,
     RenderTemplate,
     SignatureReflection,
-    SomeType
+    Type
 } from 'typedoc';
 import { index } from './partials';
 import { comment } from './partials/comment';
@@ -26,18 +25,13 @@ import { reflectionTemplate } from './partials/reflection';
 import { type } from './partials/type';
 
 export class FdThemeContext extends DefaultThemeRenderContext {
+    override analytics = () => <></>;
     override footer = () => <></>;
     override header = () => <></>;
     override sidebar = () => <></>;
     override pageSidebar = () => <></>;
     override toolbar = () => <></>;
-    override member = (props: DeclarationReflection | DocumentReflection) => {
-        if (props instanceof DeclarationReflection || props instanceof SignatureReflection) {
-            return member(this, props);
-        }
-        // Handle DocumentReflection accordingly, if needed
-        return <>{JSON.stringify(props)}</>; // Example placeholder for handling DocumentReflection
-    };
+    override member = (props: DeclarationReflection) => member(this, props);
     override memberSignatures = (props: DeclarationReflection) => memberSignatures(this, props);
     comment = (props: Reflection) => comment(props);
     override commentTags = (props: Reflection) => commentTags(this, props);
@@ -53,7 +47,7 @@ export class FdThemeContext extends DefaultThemeRenderContext {
 
     override memberGetterSetter = (props: DeclarationReflection) => memberGetterSetter(this, props);
 
-    override type = (tp: SomeType | undefined) => type(this, tp);
+    override type = (tp: Type | undefined) => type(this, tp);
 
     override reflectionTemplate = (props: PageEvent<ContainerReflection>) => reflectionTemplate(this, props);
 }
diff --git a/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/member.declaration.tsx b/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/member.declaration.tsx
@@ -1,7 +1,18 @@
-import { DeclarationReflection, DefaultThemeRenderContext, JSX } from 'typedoc';
+import { DeclarationReflection, DefaultThemeRenderContext, JSX, ReflectionType } from 'typedoc';
 import { getKindClass, hasTypeParameters, renderTypeParametersSignature, wbr } from '../utils';
 
 export function memberDeclaration(context: DefaultThemeRenderContext, props: DeclarationReflection) {
+    function renderTypeDeclaration(type: ReflectionType) {
+        return (
+            <div class="tsd-type-declaration">
+                <h4>Type declaration</h4>
+                {context.parameter(type.declaration)}
+            </div>
+        );
+    }
+
+    const visitor = { reflection: renderTypeDeclaration };
+
     return (
         <>
             <div class="tsd-signature tsd-kind-icon">
@@ -27,7 +38,14 @@ export function memberDeclaration(context: DefaultThemeRenderContext, props: Dec
 
             {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
 
-            {props.type && context.typeDeclaration(props.type)}
+            {props.type?.visit<JSX.Children>({
+                reflection: renderTypeDeclaration,
+                array: (arr) => arr.elementType.visit(visitor),
+                intersection: (int) => int.types.map((t) => t.visit(visitor)),
+                union: (union) => union.types.map((t) => t.visit(visitor)),
+                reference: (ref) => ref.typeArguments?.map((t) => t.visit(visitor)),
+                tuple: (ref) => ref.elements.map((t) => t.visit(visitor))
+            })}
 
             {context.commentTags(props)}
 

diff --git a/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/member.tsx b/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/member.tsx
@@ -1,4 +1,4 @@
-import { DeclarationReflection, DefaultThemeRenderContext, JSX } from 'typedoc';
+import { DeclarationReflection, DefaultThemeRenderContext, JSX, ReferenceReflection } from 'typedoc';
 import { classNames, getDisplayName, reflectionFlags, wbr } from '../utils';
 
 export function member(context: DefaultThemeRenderContext, props: DeclarationReflection) {
@@ -26,7 +26,9 @@ export function member(context: DefaultThemeRenderContext, props: DeclarationRef
                 ? context.memberSignatures(props)
                 : props.hasGetterOrSetter()
                   ? context.memberGetterSetter(props)
-                  : context.memberDeclaration(props)}
+                  : props instanceof ReferenceReflection
+                    ? context.memberReference(props)
+                    : context.memberDeclaration(props)}
 
             {props.groups?.map((item) => item.children.map((item) => !item.hasOwnDocument && context.member(item)))}
         </section>

diff --git a/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/reflection.tsx b/libs/nx-plugin/src/executors/compile-typedoc/theme/partials/reflection.tsx
@@ -5,9 +5,9 @@ import {
     JSX,
     PageEvent,
     ReflectionKind,
-    SignatureReflection
+    ReflectionType
 } from 'typedoc';
-import { classNames, fixedMarkdown, getKindClass, hasTypeParameters } from '../utils';
+import { classNames, fixedMarkdown, hasTypeParameters } from '../utils';
 
 export function reflectionTemplate(context: DefaultThemeRenderContext, props: PageEvent<ContainerReflection>) {
     if (
@@ -62,12 +62,23 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
                     {!!props.model.signatures && (
                         <section class="tsd-panel">{context.memberSignatures(props.model)}</section>
                     )}
-                    {!!props.model.indexSignatures?.length && (
+                    {!!props.model.indexSignature && (
                         <section class={classNames({ 'tsd-panel': true }, context.getReflectionClasses(props.model))}>
-                            <h4 class="tsd-before-signature">{context.i18n.theme_indexable()}</h4>
-                            <ul class="tsd-signatures">
-                                {props.model.indexSignatures.map((index) => renderIndexSignature(context, index))}
-                            </ul>
+                            <h4 class="tsd-before-signature">Indexable</h4>
+                            <div class="tsd-signature">
+                                <span class="tsd-signature-symbol">[</span>
+                                {props.model.indexSignature.parameters!.map((item) => (
+                                    <>
+                                        {item.name}: {context.type(item.type)}
+                                    </>
+                                ))}
+                                <span class="tsd-signature-symbol">]: </span>
+                                {context.type(props.model.indexSignature.type)}
+                            </div>
+                            {context.commentSummary(props.model.indexSignature)}
+                            {context.commentTags(props.model.indexSignature)}
+                            {props.model.indexSignature?.type instanceof ReflectionType &&
+                                context.parameter(props.model.indexSignature.type.declaration)}
                         </section>
                     )}
                     {/* {!props.model.signatures && context.memberSources(props.model)} */}
@@ -78,24 +89,3 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
         </>
     );
 }
-
-function renderIndexSignature(context: DefaultThemeRenderContext, index: SignatureReflection) {
-    return (
-        <li class="tsd-index-signature">
-            <div class="tsd-signature">
-                {index.flags.isReadonly && <span class="tsd-signature-keyword">readonly </span>}
-                <span class="tsd-signature-symbol">[</span>
-                {index.parameters!.map((item) => (
-                    <>
-                        <span class={getKindClass(item)}>{item.name}</span>: {context.type(item.type)}
-                    </>
-                ))}
-                <span class="tsd-signature-symbol">]: </span>
-                {context.type(index.type)}
-            </div>
-            {context.commentSummary(index)}
-            {context.commentTags(index)}
-            {context.typeDetailsIfUseful(index.type)}
-        </li>
-    );
-}