Merge branch 'next' into docs-normalize-blocks

cypress/e2e/api.cy.ts

@@ -43,7 +43,7 @@ describe('API Test', () => {
 
         cy.request({
           method: 'HEAD',
-          url: `/api/${link}`,
+          url: link,
           failOnStatusCode: false,
         })
           .should(({ status }) => {

docs/.vitepress/api-pages.ts

@@ -2,6 +2,7 @@
 // Run 'pnpm run generate:api-docs' to update
 export const apiPages = [
   { text: 'Overview', link: '/api/' },
+  { text: 'Faker', link: '/api/faker.html' },
   { text: 'Airline', link: '/api/airline.html' },
   { text: 'Animal', link: '/api/animal.html' },
   { text: 'Color', link: '/api/color.html' },
@@ -28,4 +29,5 @@ export const apiPages = [
   { text: 'System', link: '/api/system.html' },
   { text: 'Vehicle', link: '/api/vehicle.html' },
   { text: 'Word', link: '/api/word.html' },
+  { text: 'Utilities', link: '/api/utils.html' },
 ];

docs/.vitepress/components/api-docs/method.ts

@@ -1,6 +1,5 @@
 export interface Method {
   readonly name: string;
-  readonly title: string;
   readonly description: string; // HTML
   readonly parameters: MethodParameter[];
   readonly returns: string;

docs/.vitepress/components/api-docs/method.vue

@@ -8,6 +8,9 @@ const props = defineProps<{ method: Method }>();
 
 function seeAlsoToUrl(see: string): string {
   const [, module, method] = see.replace(/\(.*/, '').split('\.');
+  if (!method) {
+    return 'faker.html#' + slugify(module);
+  }
   return module + '.html#' + slugify(method);
 }
 </script>

docs/api/ApiIndex.vue

@@ -97,13 +97,11 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
       <div class="api-groups">
         <div v-for="item of section.items" :key="item.text" class="api-group">
           <h3>
-            <a :href="item.link + '.html'">{{ item.text }}</a>
+            <a :href="item.link">{{ item.text }}</a>
           </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
-              <a :href="item.link + '.html#' + slugify(h.anchor)">{{
-                h.text
-              }}</a>
+              <a :href="item.link + '#' + slugify(h.anchor)">{{ h.text }}</a>
             </li>
           </ul>
         </div>

scripts/apidoc.ts

@@ -1,10 +1,8 @@
-import { faker } from '../src';
 import { generate } from './apidoc/generate';
 import { initMarkdownRenderer } from './apidoc/signature';
 
 async function build(): Promise<void> {
   await initMarkdownRenderer();
-  faker.setDefaultRefDate(Date.UTC(2023, 0, 1));
   await generate();
 }
 

scripts/apidoc/apiDocsWriter.ts

@@ -2,16 +2,17 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
-import type { APIGroup, APIItem } from '../../docs/api/api-types';
+import type { APIGroup } from '../../docs/api/api-types';
 import { formatMarkdown, formatTypescript } from './format';
+import { extractSourceBaseUrl } from './typedoc';
+import type { DocsApiDiffIndex, ModuleSummary, Page } from './utils';
 import {
-  extractModuleName,
-  extractSourceBaseUrl,
-  selectApiMethods,
-  selectApiModules,
-} from './typedoc';
-import type { DocsApiDiffIndex, PageIndex } from './utils';
-import { pathDocsDiffIndexFile, pathDocsDir, pathOutputDir } from './utils';
+  diffHash,
+  methodDiffHash,
+  pathDocsDiffIndexFile,
+  pathDocsDir,
+  pathOutputDir,
+} from './utils';
 
 const pathDocsApiPages = resolve(pathDocsDir, '.vitepress', 'api-pages.ts');
 const pathDocsApiSearchIndex = resolve(
@@ -29,6 +30,52 @@ editLink: false
 
 `;
 
+/**
+ * Writes the api docs for the given modules.
+ *
+ * @param moduleName The name of the module to write the docs for.
+ * @param lowerModuleName The lowercase name of the module.
+ * @param comment The module comments.
+ * @param deprecated The deprecation message.
+ * @param methods The methods of the module.
+ */
+export function writeApiDocsModule(
+  moduleName: string,
+  lowerModuleName: string,
+  comment: string,
+  deprecated: string | undefined,
+  methods: Method[]
+): ModuleSummary {
+  writeApiDocsModulePage(
+    moduleName,
+    lowerModuleName,
+    comment,
+    deprecated,
+    methods
+  );
+  writeApiDocsModuleData(lowerModuleName, methods);
+
+  return {
+    text: moduleName,
+    link: `/api/${lowerModuleName}.html`,
+    methods,
+    diff: methods.reduce(
+      (data, method) => ({
+        ...data,
+        [method.name]: methodDiffHash(method),
+      }),
+      {
+        moduleHash: diffHash({
+          name: moduleName,
+          field: lowerModuleName,
+          deprecated,
+          comment,
+        }),
+      }
+    ),
+  };
+}
+
 /**
  * Writes the api page for the given module to the correct location.
  *
@@ -37,7 +84,7 @@ editLink: false
  * @param comment The module comments.
  * @param methods The methods of the module.
  */
-export function writeApiDocsModulePage(
+function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
@@ -94,7 +141,7 @@ export function writeApiDocsModulePage(
  * @param lowerModuleName The lowercase name of the module.
  * @param methods The methods data to save.
  */
-export function writeApiDocsData(
+function writeApiDocsModuleData(
   lowerModuleName: string,
   methods: Method[]
 ): void {
@@ -116,10 +163,9 @@ export function writeApiDocsData(
  *
  * @param pages The pages to write into the index.
  */
-export function writeApiPagesIndex(pages: PageIndex): void {
+export function writeApiPagesIndex(pages: Page[]): void {
   // Write api-pages.ts
   console.log('Updating api-pages.ts');
-  pages.sort((a, b) => a.text.localeCompare(b.text));
   pages.splice(0, 0, { text: 'Overview', link: '/api/' });
   let apiPagesContent = `
     // This file is automatically generated.
@@ -146,33 +192,20 @@ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void {
  *
  * @param project The typedoc project.
  */
-export function writeApiSearchIndex(project: ProjectReflection): void {
-  const apiIndex: APIGroup[] = [];
-
-  const moduleApiSection: APIGroup = {
-    text: 'Module API',
-    items: [],
-  };
-
-  apiIndex.push(moduleApiSection);
-
-  const apiModules = selectApiModules(project);
-
-  moduleApiSection.items = apiModules
-    .map((module) => {
-      const moduleName = extractModuleName(module);
-      const apiSection: APIItem = {
-        text: moduleName,
-        link: moduleName.toLowerCase(),
-        headers: selectApiMethods(module).map((child) => ({
-          anchor: child.name,
-          text: child.name,
+export function writeApiSearchIndex(pages: ModuleSummary[]): void {
+  const apiIndex: APIGroup[] = [
+    {
+      text: 'Module API',
+      items: pages.map((module) => ({
+        text: module.text,
+        link: module.link,
+        headers: module.methods.map((method) => ({
+          anchor: method.name,
+          text: method.name,
         })),
-      };
-
-      return apiSection;
-    })
-    .sort((a, b) => a.text.localeCompare(b.text));
+      })),
+    },
+  ];
 
   writeFileSync(pathDocsApiSearchIndex, JSON.stringify(apiIndex));
 }

scripts/apidoc/fakerClass.ts

@@ -0,0 +1,48 @@
+import type { DeclarationReflection, ProjectReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
+import type { Method } from '../../docs/.vitepress/components/api-docs/method';
+import { writeApiDocsModule } from './apiDocsWriter';
+import { processModuleMethods } from './moduleMethods';
+import { analyzeSignature, toBlock } from './signature';
+import { selectApiSignature } from './typedoc';
+import type { ModuleSummary } from './utils';
+
+export function processFakerClass(project: ProjectReflection): ModuleSummary {
+  const fakerClass = project
+    .getChildrenByKind(ReflectionKind.Class)
+    .filter((clazz) => clazz.name === 'Faker')[0];
+
+  if (!fakerClass) {
+    throw new Error('Faker class not found');
+  }
+
+  return processClass(fakerClass);
+}
+
+function processClass(fakerClass: DeclarationReflection): ModuleSummary {
+  console.log(`Processing Faker class`);
+  const comment = toBlock(fakerClass.comment);
+  const methods: Method[] = [];
+
+  console.debug(`- constructor`);
+  methods.push(processConstructor(fakerClass));
+
+  methods.push(...processModuleMethods(fakerClass, 'faker.'));
+
+  return writeApiDocsModule('Faker', 'faker', comment, undefined, methods);
+}
+
+function processConstructor(fakerClass: DeclarationReflection): Method {
+  const constructor = fakerClass.getChildrenByKind(
+    ReflectionKind.Constructor
+  )[0];
+
+  const signature = selectApiSignature(constructor);
+
+  const method = analyzeSignature(signature, '', 'new Faker');
+
+  return {
+    ...method,
+    name: 'constructor',
+  };
+}

scripts/apidoc/fakerUtilities.ts

@@ -0,0 +1,32 @@
+import type { DeclarationReflection, ProjectReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
+import type { Method } from '../../docs/.vitepress/components/api-docs/method';
+import { writeApiDocsModule } from './apiDocsWriter';
+import { processMethods } from './moduleMethods';
+import { selectApiSignature } from './typedoc';
+import type { ModuleSummary } from './utils';
+
+export function processFakerUtilities(
+  project: ProjectReflection
+): ModuleSummary {
+  const fakerUtilities = project
+    .getChildrenByKind(ReflectionKind.Function)
+    .filter((method) => !method.flags.isPrivate);
+
+  return processUtilities(fakerUtilities);
+}
+
+function processUtilities(
+  fakerUtilities: DeclarationReflection[]
+): ModuleSummary {
+  console.log(`Processing Faker Utilities`);
+  const comment = 'A list of all the utilities available in Faker.js.';
+
+  const methods: Method[] = processMethods(
+    Object.fromEntries(
+      fakerUtilities.map((method) => [method.name, selectApiSignature(method)])
+    )
+  );
+
+  return writeApiDocsModule('Utilities', 'utils', comment, undefined, methods);
+}

scripts/apidoc/generate.ts

@@ -5,7 +5,9 @@ import {
   writeApiSearchIndex,
   writeSourceBaseUrl,
 } from './apiDocsWriter';
-import { processModuleMethods } from './moduleMethods';
+import { processFakerClass } from './fakerClass';
+import { processFakerUtilities } from './fakerUtilities';
+import { processModules } from './moduleMethods';
 import { loadProject } from './typedoc';
 import { pathOutputDir } from './utils';
 
@@ -20,12 +22,16 @@ export async function generate(): Promise<void> {
   // Useful for manually analyzing the content
   await app.generateJson(project, pathOutputJson);
 
-  const modules = processModuleMethods(project);
-  writeApiPagesIndex(modules.map(({ text, link }) => ({ text, link })));
+  const pages = [
+    processFakerClass(project),
+    ...processModules(project).sort((a, b) => a.text.localeCompare(b.text)),
+    processFakerUtilities(project),
+  ];
+  writeApiPagesIndex(pages.map(({ text, link }) => ({ text, link })));
   writeApiDiffIndex(
-    modules.reduce((data, { text, diff }) => ({ ...data, [text]: diff }), {})
+    pages.reduce((data, { text, diff }) => ({ ...data, [text]: diff }), {})
   );
+  writeApiSearchIndex(pages);
 
-  writeApiSearchIndex(project);
   writeSourceBaseUrl(project);
 }