Tracking doc: migrating to TSDoc

[jackfranklin]

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.

[jasonswearingen]

Hi @jackfranklin is there a page/readme somewhere explaining the new doc workflow? specifically, I'm currious as to the workflow for turning the tsdocs into a user facing doc site. (github readmes?)

if this is already implemented somewhere (such as when running npm run generate-docs) just elt me know and I'll walk myself through that.

thanks

[jackfranklin]

@jasonswearingen not yet; right now the docs get outputted as Markdown into the new-docs folder which GitHub does a good job of rendering. It's likely we'd just ship with that initially and then explore further options.

[Hanaffi]

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

[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!

[ashiscs]

Hello, @lumbridge01 sir I am interested in this project and want to contribute as a GSOC student.
So how should I start contributing?

[anthonrodgrs01]

Hello @lumbridge01 @jackfranklin sir, I went through the issue and and I also visited @lumbridge01 repository which is really well describe by him,

I want to start contributing, but I don't know where to begin as @lumbridge01 they have covered a lot of the documenting, So to address this issue can someone link us to the work that is left to do, and we can start by Migrating the documentation to tsDoc

Simply can anyone tell me if I have to Contribute from where can I get the Mark down documentation and how do I know what is remaining to do

[tusharpandey13]

Hi @jackfranklin. I would like to take up this issue. Will update regularly with changes/progress.

[Rahulm2310]

Hi @jackfranklin, I am getting 404 Page not found on visiting this link mentioned above https://github.com/puppeteer/puppeteer/tree/main/new-docs.

[HousewifeHacker]

Hi. I'm Jessie in Puerto Rico. I am a nontraditional student, returning to school after a long hiatus. I have formerly worked as a Python and JavaScript developer including using Puppeteer for PDFs and Selenium for testing. I'd like to get better with TypeScript and would like to contribute as a GSOC student.

[jackfranklin]

Closing this issue as we've completed the bulk of this work.

[jasonswearingen]

@jackfranklin is there a explanation of the new doc workflow somewhere? looking around the repo I still don't see it. I see /utils/doclint/ which looks interesting though!

[max-hk]

@jackfranklin is there a explanation of the new doc workflow somewhere? looking around the repo I still don't see it. I see /utils/doclint/ which looks interesting though!

I found that confusing too.

Same paragraphs were added to both api.md and the corresponding TypeScript file, like this one. But some other paragraphs were introduced to api.md only, like this one.

How do maintainers synchronize paragraphs between api.md and TypeScript files?