From dba1b2d9cc0ccc45cb65b9de3e9425a308c01eec Mon Sep 17 00:00:00 2001
From: Alex Rudenko <OrKoN@users.noreply.github.com>
Date: Tue, 11 Apr 2023 14:47:25 +0200
Subject: [PATCH] docs: add readme to the API reference index (#10001)

---
 docs/browsers-api/index.md  | 29 ++++++++++++++++++++++++++++-
 packages/browsers/README.md | 20 +++-----------------
 tools/generate_docs.ts      | 11 ++++++++++-
 3 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/docs/browsers-api/index.md b/docs/browsers-api/index.md
index aa692ab7917..a4bc8c59ad0 100644
--- a/docs/browsers-api/index.md
+++ b/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
 
diff --git a/packages/browsers/README.md b/packages/browsers/README.md
index 64a68c2f45c..f46f5bf9f1b 100644
--- a/packages/browsers/README.md
+++ b/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
diff --git a/tools/generate_docs.ts b/tools/generate_docs.ts
index f792e20c965..7184a8bc85d 100644
--- a/tools/generate_docs.ts
+++ b/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();
 })();