docs: rewrite api-docs generation using TS-AST

[ST-DDT]

This PR replaces the typedoc based api-doc generation with one that uses the typescript AST.

This PR is work in progress, but if you have suggestions please let me know.

[ST-DDT]

I found some broken JSDocs (see diff in this PR), that should be fixed in a separate PR before starting v9.0. If anyone is interested in creating PRs for that please let me know. Otherwise I will do them when I have time.

[ST-DDT]

Looks like I have plenty of time during my travel now, so I'll tackle the jsdocs now.

[ST-DDT]

I completed reading ~~all~~/most data required to build the apidocs. The following things are still missing though.

• the full signature in the examples (without jsdocs)
• the md -> html conversion prior to writing the page data
• option parameters

[ST-DDT]

How should we display the signature of the method:

1. 

(no pre and suffixes)

or

2. 

(function prefix and semicolon suffix)

or

3. 

(faker.module prefix and no suffix)

or <insert suggestion here>?

---

And should we display the signature along with the examples or should we put them in a different code block?

[Shinigami92]

How should we display the signature of the method:

1. 

(no pre and suffixes)

or

2. 

(function prefix and semicolon suffix)

or

3. 

(faker.module prefix and no suffix)

or <insert suggestion here>?

---

And should we display the signature along with the examples or should we put them in a different code block?

2. because of correct syntax highlighting

I'm also a fan of semicolon

[matthewmayer]

I would put them in seperate code blocks. Perhaps they should also have subheaders?

Parameters

Examples

Signature

Source

[Shinigami92]

I cant see the images somehow, but yeah. I like the idea of separating the examples from the signature

[ST-DDT]

I would put them in seperate code blocks. Perhaps they should also have subheaders?

Good idea. I will do all layout changes in a different PR (along the signature tabs), I'll prepare it in the data structures though. This PR is already large enough as is.

[ST-DDT]

I cant see the images somehow

There arent any images in matthewmayer's mockup to see in the first place.

[matthewmayer]

I cant see the images somehow

There arent any images in matthewmayer's mockup to see in the first place.

ah those are just empty <code> blocks in my comment, not broken images :)

[matthewmayer]

I must admit to knowing very little about how this works under the hood. What's the main advantage of this change? Faster? Less dependencies? More flexible on the output format?

[ST-DDT]

What's the main advantage of this change? Faster? Less dependencies? More flexible on the output format?

• Better access to the actual source values (specifically options jsdocs)
• provides access to the "raw" values instead of partially markdown-ified values (specifically the examples)
• It can be used for our v9 code refactoring for the standalone functions (the tooling not this code/PR).

[ST-DDT]

The generate api docs are mostly the same, currently there is only a diff in the following files:

• [x] airline
• [x] date
• [x] finance
• [x] helpers
• [x] internet
• [x] lorem
• [x] random
• [x] string
• [x] system
• [x] word

Most of them should be very minor such as {\n max: number,\n min: number\n} vs { min: number; max: number; }

ToCheck:

• [x] @see tags
• [x] are the methods sorted correctly e.g. helpers.replaceSymbols

[ST-DDT]

• [x] Check LiteralUnion<'a' | 'b'> -> 'a' | 'b' | ? https://github.com/faker-js/faker/pull/1953#issuecomment-1666888020

[ST-DDT]

TODOs:

• [x] Figure out what to do with that line: https://github.com/faker-js/faker/blob/db88a1518e8d0ccfe191bd48a1ae8641a9a25303/src/faker.ts#L59 because it actually throws in the tests now.
• [x] Fix SignatureTests tests

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.94%. Comparing base (7dae52b) to head (a92711c).

Additional details and impacted files

@@           Coverage Diff           @@
##             next    #2628   +/-   ##
=======================================
  Coverage   99.93%   99.94%           
=======================================
  Files        2960     2960           
  Lines      211617   211617           
  Branches      951      954    +3     
=======================================
+ Hits       211478   211493   +15     
+ Misses        139      120   -19     
- Partials        0        4    +4     

see 6 files with indirect coverage changes

[ST-DDT]

This is almost done. It is currently waiting for #2668 to be merged + a final review by myself + a short review guide for other reviewers.

• #2668

[ST-DDT]

Ready to review

---

Guide to review this PR:

• Have a look at the generated output (or try your own code example with pnpm run docs:dev:api-docs)
• Backup docs/api from next and diff it to the newly generated ones
• Diff test/scripts/apidoc/__snapshots__/module.spec.ts.snap vs test/scripts/apidoc/__snapshots__/class.spec.ts.snap
• Diff test/scripts/apidoc/__snapshots__/signature.spec.ts.snap vs test/scripts/apidoc/__snapshots__/method.spec.ts.snap
• Have a look at the code itself

Please mark all "debug" code you think should not be in the final merge.

[WikiRik]

Would this fix https://github.com/faker-js/faker/issues/2432 as well by any chance?

[ST-DDT]

Would this fix #2432 as well by any chance?

AFAICT: No, it doesn't because it is caused by a different set of issues.

Mainly:

function foobar(options?: {...}) {
  const { ... } = options ?? {};
}
// vs
function foobar(options: {...} = {}) {
  const { ... } = options;
}

For which method did you encounter that problem?

[ST-DDT]

• Later we could enhance the dev logs by using e.g. https://github.com/poppinss/cliui With that it is possible to create progressive logs like in this example: https://github.com/poppinss/cliui#tasks

Please keep in mind that we explicitly disabled that feature for other things such as vitest.

[Shinigami92]

• Later we could enhance the dev logs by using e.g. poppinss/cliui With that it is possible to create progressive logs like in this example: poppinss/cliui#tasks

Please keep in mind that we explicitly disabled that feature for other things such as vitest.

I'm not sure if this is related with each other 🤔 Also it would be just a pure DX faker internal thing.

[netlify[bot]]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	a92711c07b7cb34cdd34b6bb755afa6ca5bc3070
🔍 Latest deploy log	https://app.netlify.com/sites/fakerjs/deploys/66072548d5cec70008438d5d
😎 Deploy Preview	https://deploy-preview-2628.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[ST-DDT]

Maybe even better, using a factory pattern.

Not sure what you are asking for here.

---

Ready for review.

[ST-DDT]

I merge this slightly early to avoid merge conflicts after the dependency updates.