Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: rewrite api-docs generation using ts-morph #2628

Merged
merged 92 commits into from
Apr 1, 2024
Merged

docs: rewrite api-docs generation using ts-morph #2628

merged 92 commits into from
Apr 1, 2024

Conversation

ST-DDT
Copy link
Member

@ST-DDT ST-DDT commented Jan 28, 2024 •
edited
Loading

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 ST-DDT added c: docs Improvements or additions to documentation p: 1-normal Nothing urgent labels Jan 28, 2024
@ST-DDT ST-DDT added this to the vAnytime milestone Jan 28, 2024
@ST-DDT ST-DDT self-assigned this Jan 28, 2024
@ST-DDT
Copy link
Member Author

ST-DDT commented Jan 28, 2024 •
edited
Loading

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
Copy link
Member Author

ST-DDT commented Jan 28, 2024

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

@ST-DDT ST-DDT mentioned this pull request Jan 28, 2024
Merged
@ST-DDT ST-DDT mentioned this pull request Feb 1, 2024
Merged
@ST-DDT
Copy link
Member Author

ST-DDT commented Feb 1, 2024 •
edited
Loading

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 ST-DDT mentioned this pull request Feb 3, 2024
Merged
ST-DDT
ST-DDT commented Feb 3, 2024
View reviewed changes
scripts/apidoc2/diff-index.ts Outdated Show resolved Hide resolved
@netlify Netlify
Copy link

netlify bot commented Mar 15, 2024 •
edited
Loading

✅ Deploy Preview for fakerjs ready!

Name Link
🔨 Latest commit a92711c
🔍 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...

QR Code

Use your smartphone camera to open QR code link.

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

xDivisionByZerox
xDivisionByZerox reviewed Mar 21, 2024
View reviewed changes
scripts/apidoc/processing/select.ts Outdated Show resolved Hide resolved
scripts/apidoc/project.ts Outdated Show resolved Hide resolved
scripts/apidoc/processing/method.ts Outdated Show resolved Hide resolved
scripts/apidoc/output/page.ts Outdated Show resolved Hide resolved
@xDivisionByZerox xDivisionByZerox mentioned this pull request Mar 21, 2024
Merged
@ST-DDT ST-DDT requested review from Shinigami92, xDivisionByZerox and a team March 23, 2024 23:25
@Shinigami92 Shinigami92 added the needs rebase There is a merge conflict label Mar 26, 2024
@ST-DDT ST-DDT removed the needs rebase There is a merge conflict label Mar 28, 2024
xDivisionByZerox
xDivisionByZerox reviewed Mar 28, 2024
View reviewed changes
Copy link
Member

@xDivisionByZerox xDivisionByZerox left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still a bit torn on the "process" naming over a simple "get" prefix. Maybe even better, using a factory pattern.

Nevertheless, I think this PR includes a lot of work. We should propably go with the current implementation for now. If we feel discomfort with maintaining the documentation in the future, we can refactor then.

Thats why these will propably be my last comment on this PR, before approving.

test/scripts/apidoc/__snapshots__/signature.spec.ts.snap Outdated Show resolved Hide resolved
test/scripts/apidocs/__snapshots__/method.spec.ts.snap Show resolved Hide resolved
scripts/apidocs/processing/type.ts Outdated Show resolved Hide resolved
scripts/apidocs/utils/value-checks.ts Outdated Show resolved Hide resolved
@ST-DDT
Copy link
Member Author

ST-DDT commented Mar 29, 2024 •
edited
Loading

Maybe even better, using a factory pattern.

Not sure what you are asking for here.

Ready for review.

@ST-DDT ST-DDT requested review from xDivisionByZerox and a team March 29, 2024 20:34
Shinigami92
Shinigami92 approved these changes Mar 31, 2024
View reviewed changes
Copy link
Member

@Shinigami92 Shinigami92 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to unblock this from merge
We can still improve in further iterations 🙂

@ST-DDT
Copy link
Member Author

ST-DDT commented Apr 1, 2024

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

@ST-DDT ST-DDT merged commit 6191a5d into next Apr 1, 2024
20 checks passed
@ST-DDT ST-DDT deleted the docs/apidocs-rewrite branch April 1, 2024 08:21
@ST-DDT ST-DDT mentioned this pull request Jun 20, 2024
Merged
@matthewmayer matthewmayer mentioned this pull request Sep 1, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Shinigami92 Shinigami92 Shinigami92 approved these changes

@xDivisionByZerox xDivisionByZerox xDivisionByZerox approved these changes

Assignees

@ST-DDT ST-DDT

Labels
c: docs Improvements or additions to documentation p: 1-normal Nothing urgent
Projects
None yet
Milestone
vAnytime
Development

Successfully merging this pull request may close these issues.
5 participants
@ST-DDT @Shinigami92 @matthewmayer @WikiRik @xDivisionByZerox