docs: add basic docs for browsers (#9867)

Co-authored-by: Nikolay Vitkov <34244704+Lightning00Blade@users.noreply.github.com>

packages/browsers/README.md

@@ -1,3 +1,42 @@
 # @puppeteer/browsers
 
-Manage and launch browsers for Puppeteer. Documentation TODO.
+Manage and launch browsers/drivers from a CLI or programmatically.
+
+## CLI
+
+Use `npx` to run the CLI without installing:
+
+```sh
+npx @puppeteer/browsers --help
+```
+
+or install the package as a dependency and run it from your `package.json` script:
+
+```sh
+npm i @puppeteer/browsers
+```
+
+```json
+{
+  "scripts": {
+    "browsers": "@puppeteer/browsers --help"
+  }
+}
+```
+
+CLI help will provide all documentation you need to use the CLI.
+
+```sh
+npx @puppeteer/browsers --help # help for all commands
+npx @puppeteer/browsers install --help # help for the install command
+npx @puppeteer/browsers launch --help # help for the launch command
+```
+
+Known limitations:
+
+1. We support installing and running Firefox and Chrome/Chromium. The `latest` keyword only works during the installation. For the `launch` command you need to specify an exact build ID. The build ID is provided by the `install` command.
+2. Launching the system browsers is only possible for Chrome/Chromium.
+
+## API
+
+The programmatic API allows installing and launching browsers from your code. See the `test` folder for examples on how to use the `install`, `canInstall`, `launch`, `computeExecutablePath`, `computeSystemExecutablePath` and other methods.

packages/browsers/src/CLI.ts

@@ -61,7 +61,8 @@ export class CLI {
 
   #defineBrowserParameter(yargs: yargs.Argv<unknown>): void {
     yargs.positional('browser', {
-      description: 'The browser version',
+      description:
+        'Which browser to install <browser>[@<buildId|latest>]. `latest` will try to find the latest available build. `buildId` is a browser-specific identifier such as a version or a revision.',
       type: 'string',
       coerce: (opt): InstallArgs['browser'] => {
         return {
@@ -77,27 +78,53 @@ export class CLI {
       type: 'string',
       desc: 'Platform that the binary needs to be compatible with.',
       choices: Object.values(BrowserPlatform),
-      defaultDescription: 'Auto-detected by default.',
+      defaultDescription: 'Auto-detected',
     });
   }
 
   #definePathParameter(yargs: yargs.Argv<unknown>): void {
     yargs.option('path', {
       type: 'string',
-      desc: 'Path to the root folder for the browser downloads and installation',
+      desc: 'Path to the root folder for the browser downloads and installation. The installation folder structure is compatible with the cache structure used by Puppeteer.',
       default: process.cwd(),
+      defaultDescription: 'Current working directory',
     });
   }
 
   async run(argv: string[]): Promise<void> {
     await yargs(hideBin(argv))
+      .scriptName('@puppeteer/browsers')
       .command(
         'install <browser>',
-        'Download and install the specified browser',
+        'Download and install the specified browser. If successful, the command outputs the actual browser buildId that was installed and the absolute path to the browser executable (format: <browser>@<buildID> <path>).',
         yargs => {
           this.#defineBrowserParameter(yargs);
           this.#definePlatformParameter(yargs);
           this.#definePathParameter(yargs);
+          yargs.example(
+            '$0 install chrome',
+            'Install the latest available build of the Chrome browser.'
+          );
+          yargs.example(
+            '$0 install chrome@latest',
+            'Install the latest available build for the Chrome browser.'
+          );
+          yargs.example(
+            '$0 install chromium@1083080',
+            'Install the revision 1083080 of the Chromium browser.'
+          );
+          yargs.example(
+            '$0 install firefox',
+            'Install the latest available build of the Firefox browser.'
+          );
+          yargs.example(
+            '$0 install firefox --platform mac',
+            'Install the latest Mac (Intel) build of the Firefox browser.'
+          );
+          yargs.example(
+            '$0 install firefox --path /tmp/my-browser-cache',
+            'Install to the specified cache directory.'
+          );
         },
         async argv => {
           const args = argv as unknown as InstallArgs;
@@ -149,6 +176,22 @@ export class CLI {
             desc: 'Search for a browser installed on the system instead of the cache folder.',
             default: false,
           });
+          yargs.example(
+            '$0 launch chrome@1083080',
+            'Launch the Chrome browser identified by the revision 1083080.'
+          );
+          yargs.example(
+            '$0 launch firefox@112.0a1',
+            'Launch the Firefox browser identified by the milestone 112.0a1.'
+          );
+          yargs.example(
+            '$0 launch chrome@1083080 --detached',
+            'Launch the browser but detach the sub-processes.'
+          );
+          yargs.example(
+            '$0 launch chrome@canary --system',
+            'Try to locate the Canary build of Chrome installed on the system and launch it.'
+          );
         },
         async argv => {
           const args = argv as unknown as LaunchArgs;
@@ -173,6 +216,7 @@ export class CLI {
       )
       .demandCommand(1)
       .help()
+      .wrap(Math.min(120, yargs.terminalWidth()))
       .parse();
   }