Skip to content

Commit

Permalink
Cleaned up Py doc sphinx warnings/errors and added README (#14191)
Browse files Browse the repository at this point in the history
- Cleaned up various sphinx build error and warnings
- Added py/docs/README.rst leaving some instructions for the next person
  • Loading branch information
emanlove authored Nov 8, 2024
1 parent 7540e09 commit d5ab5ff
Show file tree
Hide file tree
Showing 4 changed files with 84 additions and 12 deletions.
71 changes: 71 additions & 0 deletions py/docs/README.rst
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 3 additions & 3 deletions py/selenium/webdriver/chromium/webdriver.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

Expand Down
10 changes: 5 additions & 5 deletions py/selenium/webdriver/common/virtual_authenticator.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 5 additions & 4 deletions py/selenium/webdriver/support/relative_locator.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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"
Expand Down

0 comments on commit d5ab5ff

Please sign in to comment.