docs: fix full url to absolute conversion (#2101)

Author: ST-DDT

scripts/apidoc/fakerClass.ts

@@ -2,9 +2,9 @@ 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 { analyzeModule, processModuleMethods } from './moduleMethods';
 import { analyzeSignature } from './signature';
-import { extractDescription, selectApiSignature } from './typedoc';
+import { selectApiSignature } from './typedoc';
 import type { ModuleSummary } from './utils';
 
 export function processFakerClass(project: ProjectReflection): ModuleSummary {
@@ -21,15 +21,15 @@ export function processFakerClass(project: ProjectReflection): ModuleSummary {
 
 function processClass(fakerClass: DeclarationReflection): ModuleSummary {
   console.log(`Processing Faker class`);
-  const comment = extractDescription(fakerClass);
+  const { comment, deprecated } = analyzeModule(fakerClass);
   const methods: Method[] = [];
 
   console.debug(`- constructor`);
   methods.push(processConstructor(fakerClass));
 
   methods.push(...processModuleMethods(fakerClass, 'faker.'));
 
-  return writeApiDocsModule('Faker', 'faker', comment, undefined, methods);
+  return writeApiDocsModule('Faker', 'faker', comment, deprecated, methods);
 }
 
 function processConstructor(fakerClass: DeclarationReflection): Method {

scripts/apidoc/markdown.ts

@@ -2,7 +2,7 @@ import sanitizeHtml from 'sanitize-html';
 import type { MarkdownRenderer } from 'vitepress';
 import { createMarkdownRenderer } from 'vitepress';
 import vitepressConfig from '../../docs/.vitepress/config';
-import { pathOutputDir } from './utils';
+import { adjustUrls, pathOutputDir } from './utils';
 
 let markdown: MarkdownRenderer;
 
@@ -57,7 +57,7 @@ export function mdToHtml(md: string, inline: boolean = false): string {
   const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions);
   // Revert some escaped characters for comparison.
   if (comparableSanitizedHtml(rawHtml) === comparableSanitizedHtml(safeHtml)) {
-    return safeHtml.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
+    return adjustUrls(safeHtml);
   }
 
   console.debug('Rejected unsafe md:', md);

scripts/apidoc/moduleMethods.ts

@@ -15,6 +15,7 @@ import {
   selectApiModules,
 } from './typedoc';
 import type { ModuleSummary } from './utils';
+import { adjustUrls } from './utils';
 
 /**
  * Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`.
@@ -34,10 +35,9 @@ export function processModules(project: ProjectReflection): ModuleSummary[] {
  */
 function processModule(module: DeclarationReflection): ModuleSummary {
   const moduleName = extractModuleName(module);
-  const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
-  const comment = extractDescription(module);
-  const deprecated = extractDeprecated(module);
+  const moduleFieldName = extractModuleFieldName(module);
+  const { comment, deprecated } = analyzeModule(module);
   const methods = processModuleMethods(module, `faker.${moduleFieldName}.`);
 
   return writeApiDocsModule(
@@ -49,6 +49,22 @@ function processModule(module: DeclarationReflection): ModuleSummary {
   );
 }
 
+/**
+ * Analyzes the documentation for a class.
+ *
+ * @param module The class to process.
+ * @returns The class information.
+ */
+export function analyzeModule(module: DeclarationReflection): {
+  comment: string;
+  deprecated: string | undefined;
+} {
+  return {
+    comment: adjustUrls(extractDescription(module)),
+    deprecated: extractDeprecated(module),
+  };
+}
+
 /**
  * Processes all api methods of the given class. This does not include the constructor.
  *

scripts/apidoc/utils.ts

@@ -43,6 +43,10 @@ export const pathOutputDir = resolve(pathDocsDir, 'api');
 
 // Functions
 
+export function adjustUrls(description: string): string {
+  return description.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
+}
+
 export function mapByName<T extends { name: string }, V>(
   input: T[],
   valueExtractor: (item: T) => V

test/scripts/apidoc/__snapshots__/module.spec.ts.snap

@@ -0,0 +1,24 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`module > analyzeModule() > ModuleFakerJsLinkTest 1`] = `
+{
+  "comment": "Description with a link to our [website](/)
+and [api docs](/api/).",
+  "deprecated": undefined,
+}
+`;
+
+exports[`module > analyzeModule() > ModuleNextFakerJsLinkTest 1`] = `
+{
+  "comment": "Description with a link to our [website](/)
+and [api docs](/api/).",
+  "deprecated": undefined,
+}
+`;
+
+exports[`module > analyzeModule() > expected and actual modules are equal 1`] = `
+[
+  "ModuleFakerJsLinkTest",
+  "ModuleNextFakerJsLinkTest",
+]
+`;

test/scripts/apidoc/module.example.ts

@@ -0,0 +1,11 @@
+/**
+ * Description with a link to our [website](https://fakerjs.dev/)
+ * and [api docs](https://fakerjs.dev/api/).
+ */
+export class ModuleFakerJsLinkTest {}
+
+/**
+ * Description with a link to our [website](https://next.fakerjs.dev/)
+ * and [api docs](https://next.fakerjs.dev/api/).
+ */
+export class ModuleNextFakerJsLinkTest {}

test/scripts/apidoc/module.spec.ts

@@ -0,0 +1,27 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown';
+import { analyzeModule } from '../../../scripts/apidoc/moduleMethods';
+import * as ModuleTests from './module.example';
+import { loadExampleModules } from './utils';
+
+describe('module', () => {
+  describe('analyzeModule()', () => {
+    const modules = loadExampleModules();
+
+    beforeAll(initMarkdownRenderer);
+
+    it('dummy dependency to rerun the test if the example changes', () => {
+      expect(Object.keys(ModuleTests)).not.toEqual([]);
+    });
+
+    it('expected and actual modules are equal', () => {
+      expect(Object.keys(modules).sort()).toMatchSnapshot();
+    });
+
+    it.each(Object.entries(modules))('%s', (_, module) => {
+      const actual = analyzeModule(module);
+
+      expect(actual).toMatchSnapshot();
+    });
+  });
+});

test/scripts/apidoc/tsconfig.json

@@ -2,5 +2,5 @@
   "compilerOptions": {
     "target": "ES5"
   },
-  "include": ["signature.example.ts"]
+  "include": ["signature.example.ts", "module.example.ts"]
 }

test/scripts/apidoc/utils.ts

@@ -39,3 +39,23 @@ export function loadExampleMethods(): Record<string, SignatureReflection> {
     true
   )['SignatureTest'][1];
 }
+
+/**
+ * Loads the example modules using TypeDoc.
+ */
+export function loadExampleModules(): Record<string, DeclarationReflection> {
+  const modules = loadProjectModules(
+    {
+      entryPoints: ['test/scripts/apidoc/module.example.ts'],
+      tsconfig: 'test/scripts/apidoc/tsconfig.json',
+    },
+    true
+  );
+
+  const result: Record<string, DeclarationReflection> = {};
+  for (const key in modules) {
+    result[key] = modules[key][0];
+  }
+
+  return result;
+}