From d5ab5ffcf2bc4a96b1bb578ee0807057340e9d50 Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 7 Nov 2024 19:24:25 -0500 Subject: [PATCH] Cleaned up Py doc sphinx warnings/errors and added README (#14191) - Cleaned up various sphinx build error and warnings - Added py/docs/README.rst leaving some instructions for the next person --- py/docs/README.rst | 71 +++++++++++++++++++ py/selenium/webdriver/chromium/webdriver.py | 6 +- .../webdriver/common/virtual_authenticator.py | 10 +-- .../webdriver/support/relative_locator.py | 9 +-- 4 files changed, 84 insertions(+), 12 deletions(-) create mode 100644 py/docs/README.rst diff --git a/py/docs/README.rst b/py/docs/README.rst new file mode 100644 index 0000000000000..8b58a410e00ff --- /dev/null +++ b/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 git@github.com: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 `_ + +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 `_. + +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. \ No newline at end of file diff --git a/py/selenium/webdriver/chromium/webdriver.py b/py/selenium/webdriver/chromium/webdriver.py index d7bf5c706a453..af563f41672a8 100644 --- a/py/selenium/webdriver/chromium/webdriver.py +++ b/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"] diff --git a/py/selenium/webdriver/common/virtual_authenticator.py b/py/selenium/webdriver/common/virtual_authenticator.py index 290a808d6ae3b..cfc467307f923 100644 --- a/py/selenium/webdriver/common/virtual_authenticator.py +++ b/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 diff --git a/py/selenium/webdriver/support/relative_locator.py b/py/selenium/webdriver/support/relative_locator.py index 3b7766a7de3de..d1ccbc257ac3f 100644 --- a/py/selenium/webdriver/support/relative_locator.py +++ b/py/selenium/webdriver/support/relative_locator.py @@ -32,11 +32,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") @@ -50,8 +51,8 @@ def locate_with(by: ByType, 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"