docs: python api review (#4986)

docs/src/api/class-accessibility.md

@@ -46,9 +46,11 @@ assistive technologies themselves. By default, Playwright tries to approximate t
 Captures the current state of the accessibility tree. The returned object represents the root accessible node of the
 page.
 
-> **NOTE** The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers.
+:::note
+The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers.
 Playwright will discard them as well for an easier to process tree, unless [`option: interestingOnly`] is set to
 `false`.
+:::
 
 An example of dumping the entire accessibility tree:
 

docs/src/api/class-browser.md

@@ -14,9 +14,6 @@ const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.
 })();
 ```
 
-See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that
-[`method: BrowserType.launch`] always returns a specific browser instance, based on the browser being launched.
-
 ## event: Browser.disconnected
 
 Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:

docs/src/api/class-browsercontext.md

@@ -44,8 +44,10 @@ const [page] = await Promise.all([
 console.log(await page.evaluate('location.href'));
 ```
 
-> **NOTE** Use [`method: Page.waitForLoadState`] to wait until the page gets to a particular state (you should not
+:::note
+Use [`method: Page.waitForLoadState`] to wait until the page gets to a particular state (you should not
 need it in most cases).
+:::
 
 ## async method: BrowserContext.addCookies
 
@@ -91,8 +93,10 @@ await browserContext.addInitScript({
 });
 ```
 
-> **NOTE** The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and
+:::note
+The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`] and
 [`method: Page.addInitScript`] is not defined.
+:::
 
 ### param: BrowserContext.addInitScript.script
 * langs: js
@@ -132,7 +136,9 @@ context.clearPermissions();
 
 Closes the browser context. All the pages that belong to the browser context will be closed.
 
-> **NOTE** the default browser context cannot be closed.
+:::note
+The default browser context cannot be closed.
+:::
 
 ## async method: BrowserContext.cookies
 - returns: <[Array]<[Object]>>
@@ -332,7 +338,9 @@ await browser.close();
 Page routes (set up with [`method: Page.route`]) take precedence over browser context routes when request matches both
 handlers.
 
-> **NOTE** Enabling routing disables http cache.
+:::note
+Enabling routing disables http cache.
+:::
 
 ### param: BrowserContext.route.url
 - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
@@ -354,8 +362,10 @@ This setting will change the default maximum navigation time for the following m
 * [`method: Page.setContent`]
 * [`method: Page.waitForNavigation`]
 
-> **NOTE** [`method: Page.setDefaultNavigationTimeout`] and [`method: Page.setDefaultTimeout`] take priority over
+:::note
+[`method: Page.setDefaultNavigationTimeout`] and [`method: Page.setDefaultTimeout`] take priority over
 [`method: BrowserContext.setDefaultNavigationTimeout`].
+:::
 
 ### param: BrowserContext.setDefaultNavigationTimeout.timeout
 - `timeout` <[float]>
@@ -366,8 +376,10 @@ Maximum navigation time in milliseconds
 
 This setting will change the default maximum time for all the methods accepting [`param: timeout`] option.
 
-> **NOTE** [`method: Page.setDefaultNavigationTimeout`], [`method: Page.setDefaultTimeout`] and [`method:
+:::note
+[`method: Page.setDefaultNavigationTimeout`], [`method: Page.setDefaultTimeout`] and [`method:
 BrowserContext.setDefaultNavigationTimeout`] take priority over [`method: BrowserContext.setDefaultTimeout`].
+:::
 
 ### param: BrowserContext.setDefaultTimeout.timeout
 - `timeout` <[float]>
@@ -380,7 +392,9 @@ The extra HTTP headers will be sent with every request initiated by any page in
 with page-specific extra HTTP headers set with [`method: Page.setExtraHTTPHeaders`]. If page overrides a particular
 header, page-specific header value will be used instead of the browser context header value.
 
-> **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests.
+:::note
+[`method: BrowserContext.setExtraHTTPHeaders`] does not guarantee the order of headers in the outgoing requests.
+:::
 
 ### param: BrowserContext.setExtraHTTPHeaders.headers
 - `headers` <[Object]<[string], [string]>>
@@ -395,8 +409,10 @@ Sets the context's geolocation. Passing `null` or `undefined` emulates position
 await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
 ```
 
-> **NOTE** Consider using [`method: BrowserContext.grantPermissions`] to grant permissions for the browser context
+:::note
+Consider using [`method: BrowserContext.grantPermissions`] to grant permissions for the browser context
 pages to read its geolocation.
+:::
 
 ### param: BrowserContext.setGeolocation.geolocation
 - `geolocation` <[null]|[Object]>
@@ -405,6 +421,7 @@ pages to read its geolocation.
   - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`.
 
 ## async method: BrowserContext.setHTTPCredentials
+* langs: js
 
 **DEPRECATED** Browsers may cache credentials after successful authentication.
 Create a new browser context instead.
@@ -481,8 +498,8 @@ Event name, same one would pass into `browserContext.on(event)`.
 
 ### param: BrowserContext.waitForEvent.optionsOrPredicate
 * langs: js
-- `optionsOrPredicate` <[Function]|[Object]>
-  - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
+- `optionsOrPredicate` <[function]|[Object]>
+  - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve.
   - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`].
 
 Either a predicate that receives an event or an options object. Optional.

docs/src/api/class-chromiumbrowser.md

@@ -14,7 +14,9 @@ await browser.stopTracing();
 
 [ChromiumBrowser] can also be used for testing Chrome Extensions.
 
-> **NOTE** Extensions in Chrome / Chromium currently only work in non-headless mode.
+:::note
+Extensions in Chrome / Chromium currently only work in non-headless mode.
+:::
 
 The following is code for getting a handle to the [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`:
 ```js

docs/src/api/class-chromiumbrowsercontext.md

@@ -12,7 +12,9 @@ const backgroundPage = await context.waitForEvent('backgroundpage');
 
 Emitted when new background page is created in the context.
 
-> **NOTE** Only works with persistent context.
+:::note
+Only works with persistent context.
+:::
 
 ## event: ChromiumBrowserContext.serviceworker
 - type: <[Worker]>

docs/src/api/class-chromiumcoverage.md

@@ -38,9 +38,11 @@ Whether to reset coverage on every navigation. Defaults to `true`.
 
 Returns coverage is started
 
-> **NOTE** Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created
+:::note
+Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created
 on the page using `eval` or `new Function`. If [`option: reportAnonymousScripts`] is set to `true`, anonymous scripts
 will have `__playwright_evaluation_script__` as their URL.
+:::
 
 ### option: ChromiumCoverage.startJSCoverage.resetOnNavigation
 - `resetOnNavigation` <[boolean]>
@@ -62,7 +64,9 @@ Whether anonymous scripts generated by the page should be reported. Defaults to
 
 Returns the array of coverage reports for all stylesheets
 
-> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
+:::note
+CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
+:::
 
 ## async method: ChromiumCoverage.stopJSCoverage
 - returns: <[Array]<[Object]>>
@@ -79,5 +83,7 @@ Returns the array of coverage reports for all stylesheets
 
 Returns the array of coverage reports for all scripts
 
-> **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
+:::note
+JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
 reported.
+:::

docs/src/api/class-download.md

@@ -17,9 +17,12 @@ const path = await download.path();
 ...
 ```
 
-> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the
-downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual
-download is not performed and user has no access to the downloaded files.
+:::note
+Browser context **must** be created with the [`option: acceptDownloads`] set to `true` when user needs access to the
+downloaded content. If [`option: acceptDownloads`] is not set, download events are
+emitted, but the actual download is not performed and user has no access to the
+downloaded files.
+:::
 
 ## async method: Download.createReadStream
 * langs: js
@@ -37,7 +40,7 @@ Deletes the downloaded file.
 Returns download error if any.
 
 ## async method: Download.path
-- returns: <[null]|[string]>
+- returns: <[null]|[path]>
 
 Returns path to the downloaded file in case of successful download.
 

docs/src/api/class-elementhandle.md

@@ -210,7 +210,9 @@ If the element is detached from the DOM at any moment during the action, this me
 When all steps combined have not finished during the specified [`option: timeout`], this method rejects with a
 [TimeoutError]. Passing zero timeout disables this.
 
-> **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
+:::note
+`elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
+:::
 
 ### option: ElementHandle.dblclick.button = %%-input-button-%%
 
@@ -502,7 +504,9 @@ If the element is detached from the DOM at any moment during the action, this me
 When all steps combined have not finished during the specified [`option: timeout`], this method rejects with a
 [TimeoutError]. Passing zero timeout disables this.
 
-> **NOTE** `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
+:::note
+`elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
+:::
 
 ### option: ElementHandle.tap.position = %%-input-position-%%
 
@@ -613,7 +617,9 @@ const div = await page.$('div');
 const span = await div.waitForSelector('span', { state: 'attached' });
 ```
 
-> **NOTE** This method does not work across navigations, use [`method: Page.waitForSelector`] instead.
+:::note
+This method does not work across navigations, use [`method: Page.waitForSelector`] instead.
+:::
 
 ### param: ElementHandle.waitForSelector.selector = %%-query-selector-%%
 

docs/src/api/class-frame.md

@@ -251,7 +251,9 @@ This method double clicks an element matching [`param: selector`] by performing
 When all steps combined have not finished during the specified [`option: timeout`], this method rejects with a
 [TimeoutError]. Passing zero timeout disables this.
 
-> **NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event.
+:::note
+`frame.dblclick()` dispatches two `click` events and a single `dblclick` event.
+:::
 
 ### param: Frame.dblclick.selector = %%-input-selector-%%
 
@@ -476,10 +478,14 @@ last redirect.
 "Not Found" and 500 "Internal Server Error".  The status code for such responses can be retrieved by calling [`method:
 Response.status`].
 
-> **NOTE** `frame.goto` either throws an error or returns a main resource response. The only exceptions are navigation
+:::note
+`frame.goto` either throws an error or returns a main resource response. The only exceptions are navigation
 to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
-> **NOTE** Headless mode doesn't support navigation to a PDF document. See the [upstream
+:::
+:::note
+Headless mode doesn't support navigation to a PDF document. See the [upstream
 issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
+:::
 
 ### param: Frame.goto.url
 - `url` <[string]>
@@ -602,8 +608,10 @@ Returns frame's name attribute as specified in the tag.
 
 If the name is empty, returns the id attribute instead.
 
-> **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed
+:::note
+This value is calculated once when the frame is created, and will not update if the attribute is changed
 later.
+:::note
 
 ## method: Frame.page
 - returns: <[Page]>
@@ -714,7 +722,9 @@ This method taps an element matching [`param: selector`] by performing the follo
 When all steps combined have not finished during the specified [`option: timeout`], this method rejects with a
 [TimeoutError]. Passing zero timeout disables this.
 
-> **NOTE** `frame.tap()` requires that the `hasTouch` option of the browser context be set to true.
+:::note
+`frame.tap()` requires that the `hasTouch` option of the browser context be set to true.
+:::
 
 ### param: Frame.tap.selector = %%-input-selector-%%
 
@@ -876,8 +886,10 @@ const [response] = await Promise.all([
 ]);
 ```
 
-**NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is
+:::note
+Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is
 considered a navigation.
+:::
 
 ### option: Frame.waitForNavigation.timeout = %%-navigation-timeout-%%
 

docs/src/api/class-jshandle.md

@@ -106,5 +106,7 @@ property to get
 
 Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**.
 
-> **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an
+:::note
+The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an
 error if the object has circular references.
+:::

docs/src/api/class-keyboard.md

@@ -64,7 +64,9 @@ After the key is pressed once, subsequent calls to [`method: Keyboard.down`] wil
 [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use
 [`method: Keyboard.up`].
 
-> **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
+:::note
+Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
+:::
 
 ### param: Keyboard.down.key
 - `key` <[string]>
@@ -79,7 +81,9 @@ Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress
 page.keyboard.insertText('嗨');
 ```
 
-> **NOTE** Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper case.
+:::note
+Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper case.
+:::
 
 ### param: Keyboard.insertText.text
 - `text` <[string]>
@@ -141,7 +145,9 @@ await page.keyboard.type('Hello'); // Types instantly
 await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
 ```
 
-> **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
+:::note
+Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
+:::
 
 ### param: Keyboard.type.text
 - `text` <[string]>