Cleaned up Py doc sphinx warnings/errors and added README

py/docs/README.rst

@@ -0,0 +1,71 @@
+==========================
+About Python Documentation
+==========================
+
+This directory, ``py/docs``, is the source for the API Reference Documentation
+and basic Python documentation as well as the main README for the GitHub and
+PyPI package.
+
+
+How to build docs
+=================
+
+One can build the Python documentation without doing a full bazel build. The
+following instructions will build the setup a virtual environment and installs tox, clones the
+selenium repo and then runs ``tox -c py/tox.ini`` building the Python documentation.
+
+.. code-block:: console
+
+    virtualenv test-py38-env
+    source test-py38-env/bin/activate
+    pip install tox
+    git clone [email protected]:SeleniumHQ/selenium.git
+    cd selenium/
+    # uncomment and switch to your development branch if needed 
+    #git switch -c feature-branch origin/feature-branch
+    tox -c py/tox.ini
+
+Works in similar manner as the larger selenium bazel doing just the python documentation portion.
+
+What is happening under the covers of tox, sphinx
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+tox is essentially a build tool for Python. Here it setups its own virtualenv and installs the
+documentation packages (sphinx and jinja2) as well as the required selenium python
+dependencies. Then tox runs the sphinx generate autodoc stub files and then builds the docs.
+
+Sphinx is .. well a much larger topic then what we could cover here. Most important to say
+here is that the docs are using the "classic" theme and than the majority of the api documentation
+is autogenerated. There is plenty of information available and currently the documentation is
+fairly small and not complex. So some basic understanding of restructed text and the Sphinx tool chain
+should be sufficient to contribute and develop the Python docs.
+
+To clean up the build / tox cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Although there is a Sphinx Makefile option to clean up using the tox environment above one can
+manually clean the build by deleting the build directory on the root (selenium/build using the
+default directory on git clone). Noting that both Sphinx and tox cache parts of their build and
+recognize changes to speed up their respective builds. But at times one wants to start fresh
+deleting the aformentioned directory will clean the Sphinx cache or removing selenium/py/.tox 
+directory for cleaning the tox environment.
+
+
+Known documentation issues
+==========================
+The API Reference primarily builds from the source code. But currently the initial template stating
+which modules to document is hard coded within py/docs/source/api.rst. So if modules are added or
+removed then the generated docs will be inaccurate. It would be preferred that the API docs generate
+soley from the code if possible. This is being tracked in `#14178 <https://github.com/SeleniumHQ/selenium/issues/14178>`_
+
+We are working through the Sphinx build Warnings and Errors trying to clean up botht the syntax and
+the build.
+
+Contributing to Python docs
+===========================
+First it is recommended that you read the main `CONTRIBUTING.md <https://github.com/SeleniumHQ/selenium/blob/trunk/CONTRIBUTING.md>`_.
+
+Some steps for contibuting to the Python documentation ..
+
+- Check out changes locally using instruction above.
+- Try to resolve any warnings/issues.
+  - If too arduous either ask for help or add to list of known issue.
+- If this process is updated please update this doc as well to help the next person.

py/selenium/webdriver/chromium/webdriver.py

@@ -77,9 +77,9 @@ def launch_app(self, id):
     def get_network_conditions(self):
         """Gets Chromium network emulation settings.
 
-        :Returns:     A dict. For example:     {'latency': 4,
-        'download_throughput': 2, 'upload_throughput': 2,     'offline':
-        False}
+        :Returns:
+            A dict.
+            For example:     {'latency': 4, 'download_throughput': 2, 'upload_throughput': 2, 'offline': False}
         """
         return self.execute("getNetworkConditions")["value"]
 
@@ -145,8 +145,7 @@ def get_sinks(self) -> list:
         return self.execute("getSinks")["value"]
 
     def get_issue_message(self):
-        """:Returns: An error message when there is any issue in a Cast
-        session."""
+        """:Returns: An error message when there is any issue in a Cast session."""
         return self.execute("getIssueMessage")["value"]
 
     def set_sink_to_use(self, sink_name: str) -> dict:

py/selenium/webdriver/common/print_page_options.py

@@ -190,7 +190,7 @@ class PrintOptions:
     - Set
         - `self.page_width` = `value`
 
-    Patameters
+    Parameters
     ----------
     `value`: `float`
 
@@ -253,7 +253,7 @@ class PrintOptions:
     -----
     - Get
         - `self.margin_left`
-    -Set
+    - Set
         - `self.margin_left` = `value`
 
     Parameters

py/selenium/webdriver/common/virtual_authenticator.py

@@ -91,11 +91,11 @@ def __init__(
 
         :Args:
             - credential_id (bytes): Unique base64 encoded string.
-            is_resident_credential (bool): Whether the credential is client-side discoverable.
-            rp_id (str): Relying party identifier.
-            user_handle (bytes): userHandle associated to the credential. Must be Base64 encoded string. Can be None.
-            private_key (bytes): Base64 encoded PKCS#8 private key.
-            sign_count (int): intital value for a signature counter.
+            - is_resident_credential (bool): Whether the credential is client-side discoverable.
+            - rp_id (str): Relying party identifier.
+            - user_handle (bytes): userHandle associated to the credential. Must be Base64 encoded string. Can be None.
+            - private_key (bytes): Base64 encoded PKCS#8 private key.
+            - sign_count (int): intital value for a signature counter.
         """
         self._id = credential_id
         self._is_resident_credential = is_resident_credential

py/selenium/webdriver/support/relative_locator.py

@@ -29,11 +29,12 @@ def with_tag_name(tag_name: str) -> "RelativeBy":
 
     Note: This method may be removed in future versions, please use
     `locate_with` instead.
+
     :Args:
         - tag_name: the DOM tag of element to start searching.
     :Returns:
-        - RelativeBy - use this object to create filters within a
-            `find_elements` call.
+        - RelativeBy: use this object to create filters within a
+              `find_elements` call.
     """
     if not tag_name:
         raise WebDriverException("tag_name can not be null")
@@ -47,8 +48,8 @@ def locate_with(by: By, using: str) -> "RelativeBy":
         - by: The value from `By` passed in.
         - using: search term to find the element with.
     :Returns:
-        - RelativeBy - use this object to create filters within a
-            `find_elements` call.
+        - RelativeBy: use this object to create filters within a
+              `find_elements` call.
     """
     assert by is not None, "Please pass in a by argument"
     assert using is not None, "Please pass in a using argument"
@@ -62,9 +63,9 @@ class RelativeBy:
 
     Example:
         lowest = driver.find_element(By.ID, "below")
-
+        
         elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
-
+        
         ids = [el.get_attribute('id') for el in elements]
         assert "above" in ids
         assert "mid" in ids