Tracking doc: migrating to TSDoc

We have recently had a week long push where many team members contributed documentation to the codebase in the form of TSDoc comments that are used to generate the documentation in the new-docs folder.

This issue is to track the remainder of the work done to migrate our documentation fully to being powered by TSDoc.

• Fix any API Extractor warnings - when running npm run generate-docs API extractor spits quite a few warnings out. We should fix these warnings (or silence any we are OK with)
• Ensure all files are documented fully. Check none were missed. For files that we deliberately don’t document (e.g. because they are internal only), we should mark them as such (with an @internal so we don’t accidentally generate docs for them)
• Decide how to document and track events that various classes emit.
• Figure out what to do with pptr.dev. Currently it parses docs/api.md to generate the interface for browsing the documentation. We have some options here:
  • we could provide a custom generator to the API Documenter to generate HTML
  • we could generate HTML from the markdown and ship that, and figure out how to layer on the search functionality.
  • we ditch pptr.dev and point to GitHub only. Either permanently, or at least in the interim.
• Remove docs/api.md and all the tooling (utils/doclint) around it

Update: 08-07-20

Chatted with @mathiasbynens and we have come up with a plan:

• Go through the TSDoc output and tidy up / fix any obvious issues. Make sure all docs from api.md are ported.
• Update docs/api.md to point users to new-docs/puppeteer.puppeteer.md.
• Update docs/api.md to contain links to old documentation on GitHub, so users on version <5 can still find the docs they need.
• For now, update pptr.dev to redirect users to GitHub to view the new docs.
• Open an issue asking users for feedback on the docs, and iterate as needed (I fully expect to find issues; we’ve moved a lot of documentation around)
• Spike into generating pptr.dev as a static website.

[lumbridge01]

Hello everyone!

I have constructed this reply as a small FAQ to try to answer questions that are going to be appearing as you start investigating this issue and to provide help to other members of the community that are looking to start coding!

🤔 Where are the docs?

As @Hanaffi said, the new-docs/ directory is not currently in the repository, as it was removed on Oct 14, 2020.

637a1f7409@puppeteer/puppeteer by @jackfranklin:

chore: gitignore new-docs (#6511) - They are generating a lot of noise in PRs. This commit removes them from git, but updates CI to generate them - to ensure there are no errors when generating the new documentation.

As the commit description indicates, they where changed to be generated via Travis CI which was then changed to Github Actions.

😲 What now?

If you are looking into investigating this issue and are interested in understanding the structure before running any code, I have restored some of the documents on main@lumbridge01/puppeteer-6118/new-docs.

If you want start tackling this challenge, I recollected:

• How the current Actions Workflow is generating the docs
• An important doc linter that has to be run before commiting
• and listed the current warnings that are to be fixed in a todo list

On lumbridge01/puppeteer-6118!

I initially updated the fork to organize the information and start working on the issue, but then I invested some extra time to explain how to get started, in the interest of helping anyone who is currently investigating this same issue!

🎉 Lets go!

I will be tackling parts of this challenge in the following days and I encourage everyone to join!

Personally, I will be tracking my progress on that repository and everyone is welcomed to contribute there if you are looking to organize similar work on a single fork.

Note: As this Issue is going to be getting extra attention in the following days, I suggest that we make the collaborative effort to notify changes that are already covered on this Issue so we do not end up working on exactly the same features at the same time!

Happy coding!

[Hanaffi]

@jackfranklin https://github.com/puppeteer/puppeteer/tree/main/new-docs This page isnt found! Can you post the link of TSDoc output?