refactor: reorganize apidoc scripts and reuse them for tests (faker-j…

…s#1759)

scripts/apidoc.ts

@@ -5,8 +5,9 @@ import {
 } from './apidoc/apiDocsWriter';
 import { processModuleMethods } from './apidoc/moduleMethods';
 import { initMarkdownRenderer } from './apidoc/signature';
+import { newTypeDocApp, patchProject } from './apidoc/typedoc';
 import type { PageIndex } from './apidoc/utils';
-import { newTypeDocApp, patchProject, pathOutputDir } from './apidoc/utils';
+import { pathOutputDir } from './apidoc/utils';
 
 const pathOutputJson = resolve(pathOutputDir, 'typedoc.json');
 

scripts/apidoc/apiDocsWriter.ts

@@ -1,17 +1,16 @@
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
-import { ReflectionKind } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import type { APIGroup, APIItem } from '../../docs/api/api-types';
-import { extractModuleName, selectApiModules } from './moduleMethods';
-import type { PageIndex } from './utils';
+import { formatMarkdown, formatTypescript } from './format';
 import {
-  formatMarkdown,
-  formatTypescript,
-  pathDocsDir,
-  pathOutputDir,
-} from './utils';
+  extractModuleName,
+  selectApiMethods,
+  selectApiModules,
+} from './typedoc';
+import type { PageIndex } from './utils';
+import { pathDocsDir, pathOutputDir } from './utils';
 
 const pathDocsApiPages = resolve(pathDocsDir, '.vitepress', 'api-pages.ts');
 const pathDocsApiSearchIndex = resolve(
@@ -139,28 +138,11 @@ export function writeApiSearchIndex(project: ProjectReflection): void {
       const apiSection: APIItem = {
         text: moduleName,
         link: moduleName.toLowerCase(),
-        headers: [],
+        headers: selectApiMethods(module).map((child) => ({
+          anchor: child.name,
+          text: child.name,
+        })),
       };
-      if (module.kind !== ReflectionKind.Property) {
-        apiSection.headers = module
-          .getChildrenByKind(ReflectionKind.Method)
-          .map((child) => ({
-            anchor: child.name,
-            text: child.name,
-          }));
-      } else {
-        // TODO @Shinigami92 2022-08-17: Extract capitalization into own function
-        apiSection.text =
-          apiSection.text.substring(0, 1).toUpperCase() +
-          apiSection.text.substring(1);
-
-        apiSection.headers = [
-          {
-            anchor: module.name,
-            text: module.name,
-          },
-        ];
-      }
 
       return apiSection;
     })

scripts/apidoc/format.ts

@@ -0,0 +1,31 @@
+import type { Options } from 'prettier';
+import { format } from 'prettier';
+import prettierConfig from '../../.prettierrc.cjs';
+
+/**
+ * Formats markdown contents.
+ *
+ * @param text The text to format.
+ */
+export function formatMarkdown(text: string): string {
+  return format(text, prettierMarkdown);
+}
+
+/**
+ * Formats typedoc contents.
+ *
+ * @param text The text to format.
+ */
+export function formatTypescript(text: string): string {
+  return format(text, prettierTypescript);
+}
+
+const prettierMarkdown: Options = {
+  ...prettierConfig,
+  parser: 'markdown',
+};
+
+const prettierTypescript: Options = {
+  ...prettierConfig,
+  parser: 'typescript',
+};

scripts/apidoc/moduleMethods.ts

@@ -1,25 +1,15 @@
 import type { DeclarationReflection, ProjectReflection } from 'typedoc';
-import { ReflectionKind } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
-import { faker } from '../../src';
 import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
 import { analyzeSignature, toBlock } from './signature';
+import {
+  extractModuleFieldName,
+  extractModuleName,
+  selectApiMethodSignatures,
+  selectApiModules,
+} from './typedoc';
 import type { PageIndex } from './utils';
 
-/**
- * Selects the modules from the project that needs to be documented.
- *
- * @param project The project used to extract the modules.
- * @returns The modules to document.
- */
-export function selectApiModules(
-  project: ProjectReflection
-): DeclarationReflection[] {
-  return project
-    .getChildrenByKind(ReflectionKind.Class)
-    .filter((module) => faker[extractModuleFieldName(module)] != null);
-}
-
 /**
  * Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`.
  *
@@ -37,24 +27,6 @@ export function processModuleMethods(project: ProjectReflection): PageIndex {
   return pages;
 }
 
-export function extractModuleName(module: DeclarationReflection): string {
-  const { name } = module;
-  // TODO @ST-DDT 2022-10-16: Remove in v10.
-  // Typedoc prefers the name of the module that is exported first.
-  if (name === 'AddressModule') {
-    return 'Location';
-  } else if (name === 'NameModule') {
-    return 'Person';
-  }
-
-  return name.replace(/Module$/, '');
-}
-
-function extractModuleFieldName(module: DeclarationReflection): string {
-  const moduleName = extractModuleName(module);
-  return moduleName.substring(0, 1).toLowerCase() + moduleName.substring(1);
-}
-
 /**
  * Analyzes and writes the documentation for a module and its methods such as `faker.animal.cat()`.
  *
@@ -69,11 +41,10 @@ function processModuleMethod(module: DeclarationReflection): PageIndex {
   const methods: Method[] = [];
 
   // Generate method section
-  for (const method of module.getChildrenByKind(ReflectionKind.Method)) {
-    const methodName = method.name;
+  for (const [methodName, signature] of Object.entries(
+    selectApiMethodSignatures(module)
+  )) {
     console.debug(`- ${methodName}`);
-    const signatures = method.signatures;
-    const signature = signatures[signatures.length - 1];
 
     methods.push(analyzeSignature(signature, moduleFieldName, methodName));
   }

scripts/apidoc/signature.ts

@@ -18,15 +18,15 @@ import type {
 } from '../../docs/.vitepress/components/api-docs/method';
 import vitepressConfig from '../../docs/.vitepress/config';
 import { faker } from '../../src';
+import { formatTypescript } from './format';
 import {
   extractRawExamples,
   extractSeeAlsos,
   extractSince,
-  formatTypescript,
   isDeprecated,
   joinTagParts,
-  pathOutputDir,
-} from './utils';
+} from './typedoc';
+import { pathOutputDir } from './utils';
 
 export function prettifyMethodName(method: string): string {
   return (