Skip to content

docs: automatically generate api docs from source #289

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
Merged
JessicaSachs merged 12 commits into from
Jan 27, 2022
Merged

docs: automatically generate api docs from source #289

JessicaSachs merged 12 commits into from
Jan 27, 2022

Conversation

@ST-DDT
Copy link
Member

@ST-DDT ST-DDT commented Jan 24, 2022 •
edited
Loading

Automatically generates the api documentation using typedocs.

Based on PR #207 by @ericjeker

  • Update Sidenav (manually)
  • Add script to generate docs
  • Generate docs (automatically)
  • Verify that the generated pages looks good
  • Remove the old api docs and generate them only during ci builds

@ST-DDT ST-DDT requested a review from a team as a code owner January 24, 2022 23:48
@ST-DDT ST-DDT changed the title docs: automatically generate docs docs: automatically generate api docs Jan 24, 2022
@ST-DDT ST-DDT changed the title docs: automatically generate api docs docs: automatically generate api docs from source Jan 24, 2022
@ST-DDT ST-DDT mentioned this pull request Jan 24, 2022
Closed
JessicaSachs
JessicaSachs previously approved these changes Jan 25, 2022
View reviewed changes
Copy link
Contributor

@JessicaSachs JessicaSachs left a comment

Choose a reason for hiding this comment

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

Pulled it down and tried it. I love this. I think we could make the parameters a little prettier, but this is so much better than what exists, I think we should merge it now.

I feel a little awkward about committing generated source code... I think we should probably have CI re-build and publish the docs instead of committing them.

BUT! Regardless, I believe it is a good first step ❤️

@ericjeker
Copy link
Contributor

ericjeker commented Jan 25, 2022

I feel a little awkward about committing generated source code... I think we should probably have CI re-build and publish the docs instead of committing them.

Yes, same. I think we shouldn't commit that, otherwise the CI will create changes in the repo files, which is not good.

@ericjeker
Copy link
Contributor

ericjeker commented Jan 25, 2022

This looks great!

Can we have the sidenav automatically generated when looping on the modules maybe? IIRC we can use Frontmatter for that? Or simply generate a Javascript array that is then processed in the .vitepress/config?

@ericjeker ericjeker mentioned this pull request Jan 25, 2022
Closed
@ST-DDT
Copy link
Member Author

ST-DDT commented Jan 25, 2022

Can we have the sidenav automatically generated when looping on the modules maybe?

I will do that.

I think we should probably have CI re-build and publish the docs instead of committing them.

My original idea was to attach it to a pre commit hook, but on the fly generation is probably best.

I think we could make the parameters a little prettier

Any suggestion how it should look like?
E.g. a table?

@Shinigami92 Shinigami92 added the c: docs Improvements or additions to documentation label Jan 25, 2022
@prisis
Copy link
Member

prisis commented Jan 25, 2022

I would only generate the code in the ci if the docs are build, so there is always up to date version live and put the docs/api to gitignore

@Shinigami92
Copy link
Member

Shinigami92 commented Jan 25, 2022

I would only generate the code in the ci if the docs are build, so there is always up to date version live and put the docs/api to gitignore

Also we have to do it like that, otherwise it could be hard to setup a CI that especially bypasses admin privileges to push into main branch

@JessicaSachs
Copy link
Contributor

JessicaSachs commented Jan 25, 2022

Yeah, build it on CI and .gitignore the local files.

@ST-DDT I was looking for inspo when I did this PR review earlier... I think Styleguidist has a decent UI

https://react-kawaii.vercel.app/#/Components?id=cat
Screen Shot 2022-01-25 at 2 53 35 AM

@Shinigami92
Copy link
Member

Shinigami92 commented Jan 25, 2022

What are your thoughts about localization support for that? #196

@ST-DDT
Copy link
Member Author

ST-DDT commented Jan 25, 2022

@JessicaSachs Like this?

I changed the command to manually generate the files to pnpm run docs:api,
but they are also generated during pnpm run build.

Shinigami92
Shinigami92 requested changes Jan 25, 2022
View reviewed changes
@Shinigami92 Shinigami92 self-requested a review January 25, 2022 17:30
Shinigami92
Shinigami92 requested changes Jan 25, 2022
View reviewed changes
@Shinigami92 Shinigami92 marked this pull request as draft January 25, 2022 21:19
Shinigami92
Shinigami92 reviewed Jan 25, 2022
View reviewed changes
@ST-DDT ST-DDT marked this pull request as ready for review January 27, 2022 15:03
@ST-DDT ST-DDT requested a review from Shinigami92 January 27, 2022 15:04
@Shinigami92
Copy link
Member

Shinigami92 commented Jan 27, 2022 •
edited
Loading

I will approve that now, but we should document

  • which script should be run by humans in which order
  • which scripts are required by CI/netlify-toml
  • which are "just" sub-scripts
    Could you open an issue for that, to track it? (or maybe it's part of Documentate teams, labels, boards ... #308)

@Shinigami92 Shinigami92 requested a review from a team January 27, 2022 16:24
@ST-DDT ST-DDT requested a review from JessicaSachs January 27, 2022 16:25
@ST-DDT ST-DDT mentioned this pull request Jan 27, 2022
Closed
@JessicaSachs JessicaSachs merged commit 35de92f into faker-js:main Jan 27, 2022
@ST-DDT ST-DDT deleted the feature/docs/auto-generate branch January 27, 2022 17:23
bmenant pushed a commit to bmenant/faker that referenced this pull request Mar 11, 2022
@ST-DDT @Shinigami92 @bmenant
docs: automatically generate api docs from source (faker-js#289)
1d062eb 
Co-authored-by: Shinigami <chrissi92@hotmail.de>
demipel8 pushed a commit to demipel8/faker that referenced this pull request Mar 11, 2022
@ST-DDT @Shinigami92 @demipel8
docs: automatically generate api docs from source (faker-js#289)
2ad96c5 
Co-authored-by: Shinigami <chrissi92@hotmail.de>
demipel8 pushed a commit to demipel8/faker that referenced this pull request Mar 11, 2022
@ST-DDT @Shinigami92 @demipel8
docs: automatically generate api docs from source (faker-js#289)
cb3c087 
Co-authored-by: Shinigami <chrissi92@hotmail.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JessicaSachs JessicaSachs JessicaSachs approved these changes

@Shinigami92 Shinigami92 Shinigami92 approved these changes

Assignees

@ST-DDT ST-DDT

Labels

c: docs Improvements or additions to documentation

Projects

None yet

Milestone

v6.0 - Ensure Project Foundation

Development

Successfully merging this pull request may close these issues.

5 participants

@ST-DDT @ericjeker @prisis @Shinigami92 @JessicaSachs