[py] Fix docstring issues that sphinx complains about (SeleniumHQ#15466)

* [py] Fix docstring errors that sphinx complained about

* [py] Fix parameter type for web_socket_url

* [py] Remove duplicate web_socket_url from BaseOptions

Author: cgoldberg

py/docs/source/index.rst

@@ -14,7 +14,7 @@ The `selenium` package is used to automate web browser interaction from Python.
 +-----------------+--------------------------------------------------------------------------------------+
 | **GitHub**:     | https://github.com/SeleniumHQ/Selenium                                               |
 +-----------------+--------------------------------------------------------------------------------------+
-| **PyPI**:       | https://pypi.org/project/selenium                                                   |
+| **PyPI**:       | https://pypi.org/project/selenium                                                    |
 +-----------------+--------------------------------------------------------------------------------------+
 | **API Docs**:   | https://selenium.dev/selenium/docs/api/py/api.html                                   |
 +-----------------+--------------------------------------------------------------------------------------+

py/selenium/webdriver/common/actions/action_builder.py

@@ -52,7 +52,7 @@ def get_device_with(self, name: str) -> Optional[Union["WheelInput", "PointerInp
         """Get the device with the given name.
 
         Parameters:
-        ----------
+        -----------
         name : str
             The name of the device to get.
 
@@ -86,7 +86,7 @@ def add_key_input(self, name: str) -> KeyInput:
         """Add a new key input device to the action builder.
 
         Parameters:
-        ----------
+        -----------
         name : str
             The name of the key input device.
 
@@ -107,7 +107,7 @@ def add_pointer_input(self, kind: str, name: str) -> PointerInput:
         """Add a new pointer input device to the action builder.
 
         Parameters:
-        ----------
+        -----------
         kind : str
             The kind of pointer input device.
                 - "mouse"
@@ -134,7 +134,7 @@ def add_wheel_input(self, name: str) -> WheelInput:
         """Add a new wheel input device to the action builder.
 
         Parameters:
-        ----------
+        -----------
         name : str
             The name of the wheel input device.
 
@@ -186,7 +186,7 @@ def _add_input(self, new_input: Union[KeyInput, PointerInput, WheelInput]) -> No
         """Add a new input device to the action builder.
 
         Parameters:
-        ----------
+        -----------
         new_input : Union[KeyInput, PointerInput, WheelInput]
             The new input device to add.
         """

py/selenium/webdriver/common/by.py

@@ -63,7 +63,7 @@ class By:
     >>> element = driver.find_element(By.TAG_NAME, 'div')
 
     CLASS_NAME:
-    ----------
+    -----------
     Select the element by its class name.
 
     >>> element = driver.find_element(By.CLASS_NAME, 'myElement')

py/selenium/webdriver/common/options.py

@@ -155,19 +155,19 @@ class BaseOptions(metaclass=ABCMeta):
     browser_version = _BaseOptionsDescriptor("browserVersion")
     """Gets and Sets the version of the browser.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.browser_version`
     - Set
         - `self.browser_version` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `str`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `str`
     - Set
@@ -177,19 +177,19 @@ class BaseOptions(metaclass=ABCMeta):
     platform_name = _BaseOptionsDescriptor("platformName")
     """Gets and Sets name of the platform.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.platform_name`
     - Set
         - `self.platform_name` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `str`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `str`
     - Set
@@ -199,19 +199,19 @@ class BaseOptions(metaclass=ABCMeta):
     accept_insecure_certs = _BaseOptionsDescriptor("acceptInsecureCerts")
     """Gets and Set whether the session accepts insecure certificates.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.accept_insecure_certs`
     - Set
         - `self.accept_insecure_certs` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `bool`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set
@@ -221,19 +221,19 @@ class BaseOptions(metaclass=ABCMeta):
     strict_file_interactability = _BaseOptionsDescriptor("strictFileInteractability")
     """Gets and Sets whether session is about file interactability.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.strict_file_interactability`
     - Set
         - `self.strict_file_interactability` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `bool`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set
@@ -243,19 +243,19 @@ class BaseOptions(metaclass=ABCMeta):
     set_window_rect = _BaseOptionsDescriptor("setWindowRect")
     """Gets and Sets window size and position.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.set_window_rect`
     - Set
         - `self.set_window_rect` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `bool`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set
@@ -265,63 +265,41 @@ class BaseOptions(metaclass=ABCMeta):
     enable_bidi = _BaseOptionsDescriptor("enableBidi")
     """Gets and Set whether the session has WebDriverBiDi enabled.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.enable_bidi`
     - Set
         - `self.enable_bidi` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `bool`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set
         - `None`
     """
 
-    web_socket_url = _BaseOptionsDescriptor("webSocketUrl")
-    """Gets and Set whether the session accepts insecure certificates.
-
-    Usage
-    -----
-    - Get
-        - `self.web_socket_url`
-    - Set
-        - `self.web_socket_url` = `value`
-
-    Parameters
-    ----------
-    `value`: `str`
-
-    Returns
-    -------
-    - Get
-        - `str` or `None`
-    - Set
-        - `None`
-    """
-
     page_load_strategy = _PageLoadStrategyDescriptor("pageLoadStrategy")
     """:Gets and Sets page load strategy, the default is "normal".
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.page_load_strategy`
     - Set
         - `self.page_load_strategy` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `str`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `str`
     - Set
@@ -332,19 +310,19 @@ class BaseOptions(metaclass=ABCMeta):
     """:Gets and Sets unhandled prompt behavior, the default is "dismiss and
     notify".
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.unhandled_prompt_behavior`
     - Set
         - `self.unhandled_prompt_behavior` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `str`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `str`
     - Set
@@ -355,19 +333,19 @@ class BaseOptions(metaclass=ABCMeta):
     """:Gets and Sets implicit timeout, pageLoad timeout and script timeout if
     set (in milliseconds)
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.timeouts`
     - Set
         - `self.timeouts` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `dict`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `dict`
     - Set
@@ -377,19 +355,19 @@ class BaseOptions(metaclass=ABCMeta):
     proxy = _ProxyDescriptor("proxy")
     """Sets and Gets Proxy.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.proxy`
     - Set
         - `self.proxy` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `Proxy`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `Proxy`
     - Set
@@ -399,19 +377,19 @@ class BaseOptions(metaclass=ABCMeta):
     enable_downloads = _BaseOptionsDescriptor("se:downloadsEnabled")
     """Gets and Sets whether session can download files.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.enable_downloads`
     - Set
         - `self.enable_downloads` = `value`
 
-    Parameters
-    ----------
+    Parameters:
+    -----------
     `value`: `bool`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set
@@ -421,19 +399,19 @@ class BaseOptions(metaclass=ABCMeta):
     web_socket_url = _BaseOptionsDescriptor("webSocketUrl")
     """Gets and Sets WebSocket URL.
 
-    Usage
-    -----
+    Usage:
+    ------
     - Get
         - `self.web_socket_url`
     - Set
         - `self.web_socket_url` = `value`
 
-    Parameters
-    ----------
-    `value`: `bool`
+    Parameters:
+    -----------
+    `value`: `str`
 
-    Returns
-    -------
+    Returns:
+    --------
     - Get
         - `bool`
     - Set