docs(python): update installation docs (#5039)

docs/src/installation-js.md

@@ -14,13 +14,13 @@ Each version of Playwright needs specific versions of browser binaries to operat
 - `~/.cache/ms-playwright` on Linux
 
 ```sh
-npm i -D playwright
+$ npm i -D playwright
 ```
 
 These browsers will take few hundreds of megabytes of the disk space when installed:
 
 ```sh
-du -hs ./Library/Caches/ms-playwright/*
+$ du -hs ./Library/Caches/ms-playwright/*
 281M  chromium-XXXXXX
 187M  firefox-XXXX
 180M  webkit-XXXX
@@ -52,9 +52,11 @@ Or you can opt into the hermetic install and place binaries under the `node_modu
 
 ```sh
 # Linux/macOS
+# Places binaries to node_modules/playwright
 $ PLAYWRIGHT_BROWSERS_PATH=0 npm i -D playwright
 
 # Windows
+# Places binaries to node_modules\playwright
 $ set PLAYWRIGHT_BROWSERS_PATH=0
 $ npm i -D playwright
 ```

docs/src/installation-python.md

@@ -0,0 +1,126 @@
+---
+id: installation
+title: "Installation"
+---
+
+<!-- TOC -->
+
+## Managing browser binaries
+
+Each version of Playwright needs specific versions of browser binaries to operate. By default Playwright downloads Chromium, WebKit and Firefox browsers into the OS-specific cache folders:
+
+- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
+- `~/Library/Caches/ms-playwright` on MacOS
+- `~/.cache/ms-playwright` on Linux
+
+```sh
+$ pip install playwright
+$ python -m playwright install
+```
+
+These browsers will take few hundreds of megabytes of the disk space when installed:
+
+```sh
+$ du -hs ./Library/Caches/ms-playwright/*
+281M  chromium-XXXXXX
+187M  firefox-XXXX
+180M  webkit-XXXX
+```
+
+You can override default behavior using environment variables. When installing Playwright, ask it to download browsers into a specific location:
+
+```sh
+# Linux/macOS
+$ pip install playwright
+$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install
+
+# Windows
+$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
+$ pip install playwright
+$ python -m playwright install
+```
+
+When running Playwright scripts, ask it to search for browsers in a shared location:
+
+```sh
+# Linux/macOS
+$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.js
+
+# Windows
+$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
+$ python playwright_script.py
+```
+
+Or you can opt into the hermetic install and place binaries under the `site-packages/playwright` folder:
+
+```sh
+# Linux/macOS
+$ pip install playwright
+$ PLAYWRIGHT_BROWSERS_PATH=0 python -m playwright install
+
+# Windows
+$ set PLAYWRIGHT_BROWSERS_PATH=0
+$ pip install playwright
+$ python -m playwright install
+```
+
+Playwright keeps track of packages that need those browsers and will garbage collect them as you update Playwright to the newer versions.
+
+:::note
+Developers can opt-in in this mode via exporting `PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers` in their `.bashrc`.
+:::
+
+## Download from artifact repository
+
+By default, Playwright downloads browsers from Microsoft and Google public CDNs.
+
+Sometimes companies maintain an internal artifact repository to host browser
+binaries. In this case, Playwright can be configured to download from a custom
+location using the `PLAYWRIGHT_DOWNLOAD_HOST` env variable.
+
+```sh
+# Linux/macOS
+$ pip install playwright
+$ PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 python -m playwright install
+
+# Windows
+$ set PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78
+$ pip install playwright
+$ python -m playwright install
+```
+
+It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that
+take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
+
+```sh
+# Linux/macOS
+$ pip install playwright
+$ PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=192.168.1.1 PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 python -m playwright install
+```
+
+## Skip browser downloads
+
+In certain cases, it is desired to avoid browser downloads altogether because
+browser binaries are managed separately.
+
+This can be done by setting `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` variable before installation.
+
+```sh
+# Linux/macOS
+$ pip install playwright
+$ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 python -m playwright install
+
+# Windows
+$ set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+$ pip install playwright
+$ python -m playwright install
+```
+
+## Download single browser binary
+
+Playwright downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument during installation.
+
+```sh
+$ pip install playwright
+$ python -m playwright install firefox
+```

docs/src/why-playwright.md

@@ -30,12 +30,19 @@ Playwright enables fast, reliable and capable automation across all modern brows
 
 * **Powerful network control**. Playwright introduces context-wide [network interception](./network.md) to stub and mock network requests.
 
-* **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs. 
+* **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs.
 
 * **Capabilities to cover all scenarios**. Support for [file downloads](./network.md) and [uploads](./input.md), out-of-process iframes, native [input events](./input.md), and even [dark mode](./emulation.md).
 
 ## Integrates with your workflow
-* **One-line installation**. Running `npm i playwright` auto-downloads browser dependencies for your team to be onboarded quickly.
+* **One-line installation**. Installing Playwright auto-downloads browser dependencies for your team to be onboarded quickly.
+  ```sh js
+  $ npm i playwright
+  ```
+  ```sh python
+  $ pip install playwright
+  $ python -m playwright install
+  ```
 
 * **TypeScript support**. Playwright ships with built-in types for auto-completion and other benefits.