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.

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

Update API docs for packages automatically #14227

Closed
63 of 77 tasks
oandregal opened this issue Mar 5, 2019 · 14 comments
Closed
63 of 77 tasks

Update API docs for packages automatically #14227

oandregal opened this issue Mar 5, 2019 · 14 comments
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time [Status] In Progress Tracking issues with work in progress [Tool] Docgen /packages/docgen [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.

Comments

@oandregal
Copy link
Member

oandregal commented Mar 5, 2019

This issue tracks the necessary work to create a command that regenerates the API documentation upon Public API changes.

By adding some code to the top-level README file of a package they get automatically updated. See instructions. There are some packages that may be more involved or need work in the tool that generates the docs (docgen), in which case they have some notes added.

Progress:

Misc:

Packages:

@gziolo
Copy link
Member

gziolo commented Mar 6, 2019

Not supported (CommonJS module).

In the majority of cases, there is nothing to auto-generate for CLI based modules so I wouldn't consider it as an issue :)

@oandregal oandregal added the [Tool] Docgen /packages/docgen label Mar 7, 2019
@oandregal
Copy link
Member Author

Only 4 reviews left! Props to @mkaz for crushing them all.

@gziolo
Copy link
Member

gziolo commented Mar 8, 2019

plugins merged and wordcount is ready to go. This leaves data and edit-post. I hope to review the latter on Monday if @mkaz doesn't beat me to it :)

@mkaz mkaz mentioned this issue Mar 8, 2019
92 tasks
@gziolo gziolo removed the Good First Issue An issue that's suitable for someone looking to contribute for the first time label Apr 10, 2019
@gziolo
Copy link
Member

gziolo commented Apr 10, 2019

@nosolosw - I don't think it's a good candidate for Good First Issue in the current form :)
Should we close this issue and open follow-up issues for the remaining work?

@oandregal
Copy link
Member Author

Agree to remove the "Good first issue". I still think it has value as a master issue, otherwise, things will become too scattered and will be difficult to understand where things stand.

@oandregal
Copy link
Member Author

Some thoughts about how to deal with current "undocumented symbols" that may or may not have a README file:

  • a minimal approach for those that have a README file: add a @see tag to the README file (not @link, though). Note that we should use an URL to GitHub, so it's reachable from other places where this is published (handbook, npm).
  • add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

cc @aduth

@aduth
Copy link
Member

aduth commented Apr 25, 2019

  • add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

By "include", do you mean output to in a similar way to the demarcations present in the top-level README files?

@aduth
Copy link
Member

aduth commented Apr 25, 2019

  • add the JSDoc to the component, and then adapt the script to include the component's README in the auto-generation process.

By "include", do you mean output to in a similar way to the demarcations present in the top-level README files?

To answer my own question, I assume that yes, it would be simple enough to add additional entry points for each of the components to output to their respective README.md files. I think the main challenge we'll face here is how to properly document Component classes in such a way which provides useful information; specifically prop types. There may be overlap with #15178, treating prop types as arguments to the constructor. It may be the sort of thing we'd want a "custom formatter" for as well.

@aduth
Copy link
Member

aduth commented Apr 25, 2019

  • a minimal approach for those that have a README file: add a @see tag to the README file (not @link, though). Note that we should use an URL to GitHub, so it's reachable from other places where this is published (handbook, npm).

Related: #15107

Edit: Pull request at #15194

@oandregal
Copy link
Member Author

There's #15421 to teach the handbook to use docgen for doc generation.

@gziolo gziolo added [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues. [Status] In Progress Tracking issues with work in progress labels May 18, 2020
@oandregal
Copy link
Member Author

Updated the list of packages. There's some new ones that are easy wins, in case anyone is interested.

@oandregal oandregal added the Good First Issue An issue that's suitable for someone looking to contribute for the first time label Jun 4, 2020
@oandregal oandregal changed the title Regenerate API docs for all packages when Public API changes Create API docs for packages automatically Jun 4, 2020
@oandregal oandregal changed the title Create API docs for packages automatically Update API docs for packages automatically Jun 4, 2020
@oandregal oandregal removed their assignment Apr 22, 2022
@DaisyOlsen
Copy link
Contributor

@oandregal are these items still relevant?

@oandregal
Copy link
Member Author

It's been a while since anyone worked on this, so I presume we can safely close it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time [Status] In Progress Tracking issues with work in progress [Tool] Docgen /packages/docgen [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.
Projects
None yet
Development

No branches or pull requests

4 participants