docs: automate the English documentation

[dayongkr]

Description

I’ve implemented an automation feature using VitePress’s dynamic routes and comment-parser with @typescript-eslint/parser to generate documentation(only reference/array).

The approach is as follows:

1. Dynamic routes and Node.js fs module are used to generate paths for each function (reference/array/[function].md, reference/array/[function].paths.mts are for Dynamic routes).
2. The source files of each function are parsed with comment-parser to extract JSDoc comments (e.g., function descriptions, parameter details) and with @typescript-eslint/parser to retrieve Function signatures and types.
3. The extracted data is then used to generate content strings through abstracted functions.

This setup allows for the English documentation to be created by simply adding a folder and two files for Dynamic routes per function category.

Before proceeding further, I’ve opened a PR to get feedback on the current implementation way. I would appreciate your feedback.

Rough flow chart

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
es-toolkit	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 4, 2024 1:51am

[codecov-commenter]

Codecov Report

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

Project coverage is 99.71%. Comparing base (3a6cb36) to head (229181a). Report is 12 commits behind head on main.

Additional details and impacted files

[](https://app.codecov.io/gh/toss/es-toolkit/pull/472?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=toss) ```diff @@ Coverage Diff @@ ## main #472 +/- ## ========================================== - Coverage 99.78% 99.71% -0.07% ========================================== Files 171 178 +7 Lines 1366 1382 +16 Branches 364 366 +2 ========================================== + Hits 1363 1378 +15 - Misses 2 3 +1 Partials 1 1 ```

[raon0211]

This is really impressive—thank you so much! I have a few thoughts:

• Would it be better to generate markdown files in our docs directory with a script instead of relying on a dynamic route?
  • I suggest this because, given that this is documentation, there are likely to be many edge cases. It might be more efficient to generate a draft of the documents that we can then edit as needed.
  • Additionally, this approach could make translations easier, as we could potentially "generate" the translated docs only once, using something like the ChatGPT API.
• Would it be possible to remove the readonly from our type generation?
  • I was actually working on something similar to this here, but we could merge the implementations...
• We should be careful with overloaded functions like zip, but I guess the current implementation is not supporting it quite properly...

[dayongkr]

First of all, thank you for your feedback. Here are my thoughts in response:

1. I chose dynamic routes for full automation, as using a draft-based approach would still require modifications if the type changes. However, I completely agree that the draft approach would be more adaptable. I also could find many edge cases when I implemented this.
2. Both cases you mentioned are fully supported at now. Please refer to the images below for reference. Additionally, it also supports scenarios with multiple jsDOCs.

I briefly looked into @deno/doc, and it seems quite powerful. However, it doesn’t provide support for the range value, meaning that I would need to generate the types manually through AST. This adds a lot of branching and code, which raises concerns regarding maintainability and stability. But it still looks great!

By the way, the development process itself was fun. So, I'm totally fine with closing this PR, merging this codes into the main branch, and then finding areas for improvement later on!

Thanks!

[dayongkr]

This issue is resolved by a9e7edde14e6f2b5a1e61262344de366879a9aee.

So I close this PR!