chore: update docs to cover python specifics (#4960)

pavelfeldman · web-flow · commit e67d89747aed · 2021-01-10T18:18:35.000-08:00
diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md
@@ -58,8 +58,8 @@ await browserContext.addCookies([cookieObject1, cookieObject2]);
 
 ### param: BrowserContext.addCookies.cookies
 - `cookies` <[Array]<[Object]>>
-  - `name` <[string]> **required**
-  - `value` <[string]> **required**
+  - `name` <[string]>
+  - `value` <[string]>
   - `url` <[string]> either url or domain / path are required. Optional.
   - `domain` <[string]> either url or domain / path are required Optional.
   - `path` <[string]> either url or domain / path are required Optional.
@@ -399,10 +399,9 @@ await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
 pages to read its geolocation.
 
 ### param: BrowserContext.setGeolocation.geolocation
-* langs: js
 - `geolocation` <[null]|[Object]>
-  - `latitude` <[float]> Latitude between -90 and 90. **required**
-  - `longitude` <[float]> Longitude between -180 and 180. **required**
+  - `latitude` <[float]> Latitude between -90 and 90.
+  - `longitude` <[float]> Longitude between -180 and 180.
   - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`.
 
 ## async method: BrowserContext.setHTTPCredentials
@@ -412,8 +411,8 @@ Create a new browser context instead.
 
 ### param: BrowserContext.setHTTPCredentials.httpCredentials
 - `httpCredentials` <[null]|[Object]>
-  - `username` <[string]> **required**
-  - `password` <[string]> **required**
+  - `username` <[string]>
+  - `password` <[string]>
 
 ## async method: BrowserContext.setOffline
 
diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md
@@ -23,7 +23,7 @@ This methods attaches Playwright to an existing browser instance.
 
 ### param: BrowserType.connect.params
 - `params` <[Object]>
-  - `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required**
+  - `wsEndpoint` <[string]> A browser websocket endpoint to connect to.
   - `slowMo` <[float]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
   - `logger` <[Logger]> Logger sink for Playwright logging. Optional.
   - `timeout` <[float]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
diff --git a/docs/src/api/class-chromiumbrowser.md b/docs/src/api/class-chromiumbrowser.md
@@ -1,6 +1,6 @@
 # class: ChromiumBrowser
-* extends: [Browser]
 * langs: js
+* extends: [Browser]
 
 Chromium-specific features including Tracing, service worker support, etc. You can use [`method:
 ChromiumBrowser.startTracing`] and [`method: ChromiumBrowser.stopTracing`] to create a trace file which can be
diff --git a/docs/src/api/class-firefoxbrowser.md b/docs/src/api/class-firefoxbrowser.md
@@ -1,4 +1,5 @@
 # class: FirefoxBrowser
+* langs: js
 * extends: [Browser]
 
 Firefox browser instance does not expose Firefox-specific features.
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
@@ -872,6 +872,7 @@ const frame = page.frame({ url: /.*domain.*/ });
 ```
 
 ### param: Page.frame.frameSelector
+* langs: js
 - `frameSelector` <[string]|[Object]>
   - `name` <[string]> Frame name specified in the `iframe`'s `name` attribute. Optional.
   - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
@@ -1467,8 +1468,8 @@ await page.goto('https://example.com');
 
 ### param: Page.setViewportSize.viewportSize
 - `viewportSize` <[Object]>
-  - `width` <[int]> page width in pixels. **required**
-  - `height` <[int]> page height in pixels. **required**
+  - `width` <[int]> page width in pixels.
+  - `height` <[int]> page height in pixels.
 
 ## async method: Page.tap
 
diff --git a/docs/src/api/class-request.md b/docs/src/api/class-request.md
@@ -15,6 +15,7 @@ If request gets a 'redirect' response, the request is successfully finished with
 request is  issued to a redirected url.
 
 ## method: Request.failure
+* langs: js
 - returns: <[null]|[Object]>
   - `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
 
diff --git a/docs/src/api/class-response.md b/docs/src/api/class-response.md
@@ -8,6 +8,7 @@
 Returns the buffer with response body.
 
 ## async method: Response.finished
+* langs: js
 - returns: <[null]|[Error]>
 
 Waits for this response to finish, returns failure error if request failed.
diff --git a/docs/src/api/class-selectors.md b/docs/src/api/class-selectors.md
@@ -49,6 +49,7 @@ Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=my
 contain `[a-zA-Z0-9_]` characters.
 
 ### param: Selectors.register.script
+* langs: js
 - `script` <[function]|[string]|[Object]>
   - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
   - `content` <[string]> Raw script content. Optional.
diff --git a/docs/src/api/class-webkitbrowser.md b/docs/src/api/class-webkitbrowser.md
@@ -1,4 +1,5 @@
 # class: WebKitBrowser
+* langs: js
 * extends: [Browser]
 
 WebKit browser instance does not expose WebKit-specific features.
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
@@ -68,9 +68,9 @@ Defaults to `left`.
 
 ## input-files
 - `files` <[path]|[Array]<[path]>|[Object]|[Array]<[Object]>>
-  - `name` <[string]> [File] name **required**
-  - `mimeType` <[string]> [File] type **required**
-  - `buffer` <[Buffer]> File content **required**
+  - `name` <[string]> [File] name
+  - `mimeType` <[string]> [File] type
+  - `buffer` <[Buffer]> File content
 
 ## input-down-up-delay
 - `delay` <[float]>
@@ -101,8 +101,8 @@ Defaults to `'visible'`. Can be either:
 ## context-option-storage-state
 - `storageState` <[path]|[Object]>
   - `cookies` <[Array]<[Object]>> Optional cookies to set for context
-    - `name` <[string]> **required**
-    - `value` <[string]> **required**
+    - `name` <[string]>
+    - `value` <[string]>
     - `url` <[string]> Optional either url or domain / path are required
     - `domain` <[string]> Optional either url or domain / path are required
     - `path` <[string]> Optional either url or domain / path are required
@@ -135,12 +135,27 @@ Whether to ignore HTTPS errors during navigation. Defaults to `false`.
 Toggles bypassing page's Content-Security-Policy.
 
 ## context-option-viewport
+* langs: js
 - `viewport` <[null]|[Object]>
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
 Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
 
+## python-context-option-viewport
+* langs: python
+- `viewport` <[null]|[Object]>
+  - `width` <[int]> page width in pixels.
+  - `height` <[int]> page height in pixels.
+
+Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `no_viewport` disables the fixed viewport.
+
+## python-context-option-no-viewport
+* langs: python
+- `noViewport` <[boolean]>
+
+Disables the default viewport.
+
 ## context-option-useragent
 - `userAgent` <[string]>
 
@@ -233,6 +248,7 @@ Logger sink for Playwright logging.
 **DEPRECATED** Use [`option: recordVideo`] instead.
 
 ## context-option-recordhar
+* langs: js
 - `recordHar` <[Object]>
   - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to
     `false`.
@@ -242,7 +258,20 @@ Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all
 specified, the HAR is not recorded. Make sure to await [`method: BrowserContext.close`] for the HAR to be
 saved.
 
+## python-context-option-recordhar-omit-content
+* langs: python
+- `record_har_omit_content` <[boolean]>
+
+Optional setting to control whether to omit request content from the HAR. Defaults to `false`.
+
+## python-context-option-recordhar-path
+* langs: python
+- `record_har_path` <[path]>
+
+Path on the filesystem to write the HAR file to.
+
 ## context-option-recordvideo
+* langs: js
 - `recordVideo` <[Object]>
   - `dir` <[path]> Path to the directory to put videos into.
   - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`.
@@ -254,6 +283,22 @@ saved.
 Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make
 sure to await [`method: BrowserContext.close`] for videos to be saved.
 
+## python-context-option-recordvideo-dir
+* langs: python
+- `record_video_dir` <[path]>
+
+Path to the directory to put videos into.
+
+## python-context-option-recordvideo-size
+* langs: python
+- `record_video_size` <[Object]>
+  If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be
+  scaled down if necessary to fit the specified size.
+  - `width` <[int]> Video frame width.
+  - `height` <[int]> Video frame height.
+
+Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`.
+
 ## context-option-proxy
 - `proxy` <[Object]>
   - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example
@@ -335,6 +380,8 @@ Optional.
 - %%-context-option-ignorehttpserrors-%%
 - %%-context-option-bypasscsp-%%
 - %%-context-option-viewport-%%
+- %%-python-context-option-viewport-%%
+- %%-python-context-option-no-viewport-%%
 - %%-context-option-useragent-%%
 - %%-context-option-devicescalefactor-%%
 - %%-context-option-ismobile-%%
@@ -352,4 +399,8 @@ Optional.
 - %%-context-option-videospath-%%
 - %%-context-option-videosize-%%
 - %%-context-option-recordhar-%%
+- %%-python-context-option-recordhar-path-%%
+- %%-python-context-option-recordhar-omit-content-%%
 - %%-context-option-recordvideo-%%
+- %%-python-context-option-recordvideo-dir-%%
+- %%-python-context-option-recordvideo-size-%%
diff --git a/docs/src/api/python.md b/docs/src/api/python.md
@@ -57,44 +57,65 @@ Script to be evaluated in all pages in the browser context. Optional.
 ### param: Page.selectOption.value = %%-python-select-options-value-%%
 ### param: Page.selectOption.label = %%-python-select-options-label-%%
 
-## async method: BrowserContext.resetGeolocation
+### param: Page.emulateMedia.params
 * langs: python
+- `media` <[null]|"screen"|"print">
 
-Emulates position unavailable state.
+Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`.
+Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value.
+Optional.
 
-### param: BrowserContext.setGeolocation.latitude
+### param: Page.emulateMedia.params
 * langs: python
-- `latitude` <[float]>
+- `colorScheme` <[null]|"light"|"dark"|"no-preference">
 
-Latitude between -90 and 90. **required**
+Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing
+`null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated
+value. Optional.
 
-### param: BrowserContext.setGeolocation.longitude
+### option: Page.frame.name
 * langs: python
-- `longitude` <[float]>
+- `name` <[string]>
 
-Longitude between -180 and 180. **required**
+Frame name specified in the `iframe`'s `name` attribute. Optional.
 
-### param: BrowserContext.setGeolocation.accuracy
+### option: Page.frame.url
 * langs: python
-- `accuracy` <[float]>
+- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
 
-Non-negative accuracy value. Defaults to `0`. Optional.
+A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
 
-### param: Page.emulateMedia.params
+### option: Selectors.register.script
 * langs: python
-- `media` <[null]|"screen"|"print">
+- `path` <[path]>
 
-Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`.
-Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value.
-Optional.
+Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory.
 
-### param: Page.emulateMedia.params
+### option: Selectors.register.script
 * langs: python
-- `colorScheme` <[null]|"light"|"dark"|"no-preference">
+- `script` <[string]>
+
+Raw script content.
+
+## method: Request.failure
+* langs: python
+- returns: <[null]|[string]>
+
+Returns human-readable error message, e.g. `'net::ERR_FAILED'`. The method returns `None` unless this request has
+failed, as reported by `requestfailed` event.
+
+Example of logging of all the failed requests:
+
+```python
+page.on('requestfailed', lambda request: print(request.url + ' ' + request.failure);
+```
+
+## async method: Response.finished
+* langs: python
+- returns: <[null]|[string]>
+
+Waits for this response to finish, returns failure error if request failed.
 
-Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing
-`null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated
-value. Optional.
 
 ### option: BrowserContext.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
 ### option: BrowserContext.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%
diff --git a/docs/src/emulation.md b/docs/src/emulation.md
@@ -267,15 +267,15 @@ const context = await browser.newContext({
 
 ```python-async
 context = await browser.new_context(
-  geolocation={ 'longitude': 48.858455, 'latitude': 2.294474 },
-  permissions=['geolocation']
+  geolocation={"longitude": 48.858455, "latitude": 2.294474},
+  permissions=["geolocation"]
 )
 ```
 
 ```python-sync
 context = browser.new_context(
-  geolocation={ 'longitude': 48.858455, 'latitude': 2.294474 },
-  permissions=['geolocation']
+  geolocation={"longitude": 48.858455, "latitude": 2.294474},
+  permissions=["geolocation"]
 )
 ```
 
@@ -286,11 +286,11 @@ await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 });
 ```
 
 ```python-async
-await context.set_geolocation(longitude=29.979097, latitude=31.134256)
+await context.set_geolocation({"longitude": 29.979097, "latitude": 31.134256})
 ```
 
 ```python-sync
-context.set_geolocation(longitude=29.979097, latitude=31.134256)
+context.set_geolocation({"longitude": 29.979097, "latitude": 31.134256})
 ```
 
 **Note** you can only change geolocation for all pages in the context.
diff --git a/types/types.d.ts b/types/types.d.ts
diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js
diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js
