Skip to content

Instantly share code, notes, and snippets.

@tasneemkoushar

tasneemkoushar/Puppeteer'sDocumentation.md

Last active January 29, 2023 16:23
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save tasneemkoushar/941128bc0d04f095fa01a5334617c65b to your computer and use it in GitHub Desktop.
Save tasneemkoushar/941128bc0d04f095fa01a5334617c65b to your computer and use it in GitHub Desktop.
Download ZIP
GSOC2021 gist by Tasneem
Raw
Puppeteer'sDocumentation.md

gsoc-logo

Final Report: GSoC '21

Problem Statement

Puppeteer’s documentation on GitHub was based on one large Markdown file, api.md, which powered the documentation on GitHub and also on pptr.dev.

This Markdown file api.md had been written manually, So whenever a new commit gets approved, it had to be mentioned manually in api.md to get reflected on the website pptr.dev.

In mid 2020, a large team sprint to move much of Puppeteer’s documentation into TSDoc, where the documentation is contained inline alongside the code (see tsdoc.org for more details).

In the long run, with future contributions to the documentation, this manual method can get bit tedious, making the repository hard to keep updated.

My mentor Jack Franklin and Mathias Bynens came up with an innovative project i.e The Automation of puppeteer's documentation, in Google Summer of code 2021.

Tools and Technology Used

Aim

  • Ensuring each file is documented with TSDoc comments and no file is left except internal files.
  • Fixing and Silencing warnings that get logged when we run any command.
  • Documenting events that classes emit so that their track gets documented nicely in the generated documentation.
  • Tooling to ensure Markdown files get updated every time some code gets committed.
  • Revamping pptr.dev by powering it with TSDoc comments, using a custom HTML generator that will automate maintenance and update of the website with every new commit that gets approved.
  • Removing all the legacy toolings (utils/ doclint) for “docs/api.md”.
  • Tooling to ensure pull requests get committed after it conforms TSDoc specifications.
  • Ensuring generated documentation and code is not out of sync.
  • Creating a Doc to guide developers to write good TSDoc documentation for their code.
  • Taking feedback from the Puppeteer’s community to deprecate the old api doc i.e “docs/api.md” by raising an issue.
  • Updating CONTRIBUTING.md file

Overview of Work Done

  • Commented all the methods, events and namespaces of all the classes
  • Fixed more than 30 warnings which was thrown because TSDoc syntax error within the existing comments.
  • Silenced lots of node module warnings, which were not part of this project.
  • Docusaurus is a documentation tool and an open source project of facebook.
  • We have used docusaurus to achieve the task of automation.
  • HTML tags in the Markdown files, are not supported by docusaurus.
  • Wrote one NodeJs synchronous script puppeteer/utils/remove-tag.js to remove these HTML tags from all our generated Markdown files.
  • Removed "bundledPackages": ["devtools-protocol"] from puppeteer/api-extractor.json which was generating around 4400 additional Markdown files, not required in our documentation website.
  • Entire doumentation code resides in puppeteer/website.
  • One workflow was required which can assure, as soon as the new commit is approved for the documentation, it should get reflected automatically on the documentation webiste on GH-Pages.
  • With the help of my mentors, I got a successful workflow.
  • Improved UI of the website.
  • Added proper names for all the APIs.
  • Included three recent version i.e V10.1.0, V10.0.0, & V9.1.1 .
  • Added one section Writing proper TSDoc Comments on puppeteer/CONTRIBUTING.md to avoid TSDoc syntax error in future contributions.
  • Added one section on puppeteer/CONTRIBUTING.md for future contributors, to give them insight on how this entire documentation is automated, step-by-step.
  • Included Algolia Search to empower users with easy search on documentation website.
  • Added link to the old documentation for the users on version<5, on our new website.

Relevant links

Potential Contribution for future

  • include all other versions of pupeeteer which are present on pptr.dev to the new website.
  • Write Proper names for APIs of those version on the sidebar.
  • Write one script to automatically update the name of classes' methods, event and namespaces on sidebar whenever a new class gets introduced to the puppeteer's repository.

Message for Future Contributors

  • This entire documentation work has been implementd from scratch in this Google Summer of Code 2021.
  • We are happy to welcome future contributions to improve UI of the website, include new features and lot more.
  • All the best to all the future contributors out there and if have any querry regarding the documentation part, please reach out to me or my mentors.
@tasneemkoushar
Copy link
Author

Hi, I Avneet singh can I contribute to your projct

Yes, you can do it in Puppeteer's Repository https://github.com/puppeteer/puppeteer. You can check its Contributing.md file to get started. At initial, you can start with writing the proper names of all the APIs present on the sidebar or adding other versions on its documentation website. You can look at these on the website Puppeteer.

@humblecoder25
Copy link

Hi, Can i contribute to your project.

@ombade
Copy link

ombade commented Nov 27, 2021

Hi, I am Om Bade can I contribute to your project

@miraj0507
Copy link

can I contribute?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment