Final Report: GSoC '21

Student: Tasneem Koushar
Github: tasneemkoushar
Organisation: Chromium
Mentors: Jack Franklin, Mathias Bynens
Project: Automation of Puppeteer's Documentation

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

api-extractor
Docusaurus
Typescript
JavaScript
Git
Github
TSDoc
Algolia Search

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

Made around 46 Pull Request
All my merged Commits
The Puppeteer's Repository
Final Website
Link to the list all the Classes and its relevant methods, events and namespaces.
Link to my Proposal

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/Puppeteer'sDocumentation.md