docs: add readme to the API reference index (#10001)

docs/browsers-api/index.md

@@ -2,7 +2,34 @@
 sidebar_label: API
 ---
 
-# API Reference
+# @puppeteer/browsers
+
+Manage and launch browsers/drivers from a CLI or programmatically.
+
+## CLI
+
+Use `npx` to run the CLI:
+
+```sh
+npx @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 (see `npx @puppeteer/browsers install --help` for the format).
+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.
 
 ## Classes
 

packages/browsers/README.md

@@ -4,26 +4,12 @@ Manage and launch browsers/drivers from a CLI or programmatically.
 
 ## CLI
 
-Use `npx` to run the CLI without installing:
+Use `npx` to run the CLI:
 
 ```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
@@ -32,9 +18,9 @@ npx @puppeteer/browsers install --help # help for the install command
 npx @puppeteer/browsers launch --help # help for the launch command
 ```
 
-Known limitations:
+## 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.
+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 (see `npx @puppeteer/browsers install --help` for the format).
 2. Launching the system browsers is only possible for Chrome/Chromium.
 
 ## API

tools/generate_docs.ts

@@ -119,7 +119,7 @@ function spliceIntoSection(
     .outputs(['docs/api'])
     .build();
 
-  job('', async ({inputs, outputs}) => {
+  await job('', async ({inputs, outputs}) => {
     await rm(outputs[0]!, {recursive: true, force: true});
     generateDocs(inputs[0]!, outputs[0]!);
     spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
@@ -130,4 +130,13 @@ function spliceIntoSection(
     ])
     .outputs(['docs/browsers-api'])
     .build();
+
+  job('', async ({inputs, outputs}) => {
+    const readme = await readFile(inputs[1]!, 'utf-8');
+    const index = await readFile(inputs[0]!, 'utf-8');
+    await writeFile(outputs[0]!, index.replace('# API Reference\n', readme));
+  })
+    .inputs(['docs/browsers-api/index.md', 'packages/browsers/README.md'])
+    .outputs(['docs/browsers-api/index.md'])
+    .build();
 })();