From fce924d43530b5122c2a0926ebdabdf106b39e24 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Tue, 18 Mar 2025 19:13:41 -0400 Subject: [PATCH 01/12] [py] Remove blank line in tox.ini --- py/tox.ini | 1 - 1 file changed, 1 deletion(-) diff --git a/py/tox.ini b/py/tox.ini index 6ae72d441c1bc..76f0a263e9018 100644 --- a/py/tox.ini +++ b/py/tox.ini @@ -14,7 +14,6 @@ skip_install = true deps = -r {toxinidir}/docs/requirements.txt -r {toxinidir}/requirements.txt - commands = ; regenerate autodoc stub pages sphinx-autogen docs/source/api.rst From ca503486d2034fa5362cc92ad0dde9a062a2a85c Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Tue, 18 Mar 2025 19:40:25 -0400 Subject: [PATCH 02/12] [py] Update instructions for docs --- py/docs/README.rst | 56 +++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/py/docs/README.rst b/py/docs/README.rst index 8b58a410e00ff..70e3c1c577afa 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -11,13 +11,13 @@ 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. +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 + python3 -m venv + source venv/bin/activate pip install tox git clone git@github.com:SeleniumHQ/selenium.git cd selenium/ @@ -25,38 +25,42 @@ selenium repo and then runs ``tox -c py/tox.ini`` building the Python documentat #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. +This works in a similar manner as the larger selenium bazel build, but does 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. +tox is essentially a build tool for Python. Here it sets up its own virtual env and installs +the documentation packages (sphinx and jinja2) as well as the required selenium python +dependencies. Then tox runs the ``sphinx-autogen`` command to generate autodoc stub pages. +Then it runs ``sphinx-build`` to build the HTML 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. +here is that the docs are using the "sphinx_rtd_theme" theme (AKA "Read the Docs" theme) and +the 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 reStructuredText 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. +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). Note that both Sphinx and tox cache parts of their build and +recognize changes to speed up their respective builds. To start fresh, delete the aformentioned +directory to clean the Sphinx cache and delete the ``selenium/py/.tox`` directory to clean 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 `_ +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 +We are working through the Sphinx build warnings and errors, trying to clean up both the syntax and the build. Contributing to Python docs @@ -65,7 +69,7 @@ First it is recommended that you read the main `CONTRIBUTING.md Date: Tue, 18 Mar 2025 19:43:15 -0400 Subject: [PATCH 03/12] [py] Bump Sphinx and Jinja2 versions for building docs --- py/docs/requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/py/docs/requirements.txt b/py/docs/requirements.txt index 37102cb397363..3b4b7a758575c 100644 --- a/py/docs/requirements.txt +++ b/py/docs/requirements.txt @@ -1,2 +1,2 @@ -Jinja2==3.1.5 -Sphinx==7.1.2 +Jinja2==3.1.6 +Sphinx==8.2.3 From 4c5704878ab153c0ffec86bf7c75a9f32ea2524f Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Tue, 18 Mar 2025 19:47:09 -0400 Subject: [PATCH 04/12] [py] Change permissions of index.rst --- py/docs/source/index.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 py/docs/source/index.rst diff --git a/py/docs/source/index.rst b/py/docs/source/index.rst old mode 100755 new mode 100644 From ad79e29ca311edb97104c8f2343064031f62fc5d Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Tue, 18 Mar 2025 20:19:01 -0400 Subject: [PATCH 05/12] [py] Update instructions for building docs --- py/docs/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/docs/README.rst b/py/docs/README.rst index 70e3c1c577afa..14bf7eaa0667c 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -23,7 +23,7 @@ clones the selenium repo and then runs ``tox -c py/tox.ini`` building the Python cd selenium/ # uncomment and switch to your development branch if needed #git switch -c feature-branch origin/feature-branch - tox -c py/tox.ini + tox -c py/tox.ini -e docs This works in a similar manner as the larger selenium bazel build, but does just the Python documentation portion. From 01c1768404db6f2f1874766e1b5807071015dc8d Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Wed, 19 Mar 2025 18:57:36 -0400 Subject: [PATCH 06/12] [py] Update Python documentation (modernization) --- py/docs/README.rst | 27 +++++++----- py/docs/requirements.txt | 1 + py/docs/selenium_logo_small.png | Bin 0 -> 647 bytes py/docs/source/conf.py | 15 +++---- py/docs/source/index.rst | 75 ++++++++++++++++++-------------- 5 files changed, 67 insertions(+), 51 deletions(-) create mode 100644 py/docs/selenium_logo_small.png diff --git a/py/docs/README.rst b/py/docs/README.rst index 14bf7eaa0667c..a73e37715a362 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -12,7 +12,8 @@ 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. +clones the selenium repo and then runs ``tox -c py/tox.ini -e docs``, building the +Python documentation. .. code-block:: console @@ -28,8 +29,10 @@ clones the selenium repo and then runs ``tox -c py/tox.ini`` building the Python This works in a similar manner as the larger selenium bazel build, but does just the Python documentation portion. + What is happening under the covers of tox, sphinx ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + tox is essentially a build tool for Python. Here it sets up its own virtual env and installs the documentation packages (sphinx and jinja2) as well as the required selenium python dependencies. Then tox runs the ``sphinx-autogen`` command to generate autodoc stub pages. @@ -42,18 +45,20 @@ available and currently the documentation is fairly small and not complex. So so understanding of reStructuredText 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). Note that both Sphinx and tox cache parts of their build and -recognize changes to speed up their respective builds. To start fresh, delete the aformentioned -directory to clean the Sphinx cache and delete the ``selenium/py/.tox`` directory to clean the -tox environment. + +To clean up the build assets and tox cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although there is a Sphinx Makefile option, to clean up using the tox environment above, one can +manually clean the build assets by deleting the ``build`` directory on the root (``selenium/build`` +using the default directory on git clone). Note that tox caches parts of the build and recognizes +changes to speed up the build. To start fresh, delete the aformentioned directory to clean the +Sphinx build assets and delete the ``selenium/py/.tox`` directory to clean 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 @@ -63,11 +68,13 @@ soley from the code if possible. This is being tracked in We are working through the Sphinx build warnings and errors, trying to clean up both 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 .. +Some steps for contibuting to the Python documentation ... - Check out changes locally using instructions above. - Try to resolve any warnings/errors. diff --git a/py/docs/requirements.txt b/py/docs/requirements.txt index 3b4b7a758575c..b64127538fa49 100644 --- a/py/docs/requirements.txt +++ b/py/docs/requirements.txt @@ -1,2 +1,3 @@ Jinja2==3.1.6 Sphinx==8.2.3 +sphinx-material==0.0.36 diff --git a/py/docs/selenium_logo_small.png b/py/docs/selenium_logo_small.png new file mode 100644 index 0000000000000000000000000000000000000000..8028a2be827d0eb51197205d718aae040ca5597b GIT binary patch literal 647 zcmV;20(kw2P)BL^VNpQnm_WbqV^4gWthlI>@xZ$p)+L`V6>XwOt-v9st6-h)v zR5;76l+SC_KorM^>9z;gg5N`60=prkOBcEnmS{axg|M{syx3Y4m9iDI;6WBV=%FyD zf}R$^QjpRWio)teQAB$w6sw?zss}yvkV_TukMPZ;`LRiQ^Bt0zeCEBp?|Uy{r>1gj z2`5;cdy{jCO#s*AKY5 zoTW%RtRGCabU9$SDbT%Wv#Jl!tq)Xv!{rlzNsdXNO0-ki1Af^lK#I#n3GtGpK+T8v z1l(sSz!*s*` zBLag2=-C2o??_nl2@kPbcNjSosYwVDR$z=akKZ(O-ObOPK%xR_EMQ%B*+3H?*g07W zJ)A(tDyvDubt>CdD^mUwI`%lqCl?pHh&srJw$_QvPQzMXTl2Nju)3#TOB_riu&>E} zRJvFhggK`y3iZMzr<+(AM@fIP-XW;^^OVdU4r-DT;v`_ | +-----------------+--------------------------------------------------------------------------------------+ @@ -33,21 +35,22 @@ If you have `pip `_ on your system, you can simply install pip install -U selenium -Alternately, you can download the source distribution from `PyPI `, unarchive it, and run:: - - python -m pip install . - -Note: You may want to consider using `virtualenv `_ to create isolated Python environments. +You may want to consider using a `virtual environment `_ +to create isolated Python environments. Drivers ======= -Selenium requires a driver to interface with the chosen browser. Firefox, -for example, requires `geckodriver `_, which needs to be installed before the below examples can be run. Make sure it's in your `PATH`, e. g., place it in `/usr/bin` or `/usr/local/bin`. +Selenium requires a driver to interface with the chosen browser (chromedriver, edgedriver, geckodriver, etc). -Failure to observe this step will give you an error `selenium.common.exceptions.WebDriverException: Message: 'geckodriver' executable needs to be in PATH.` +In older versions of Selenium, it was necessary to install and manage these drivers yourself. You had to make sure the driver +executable was available on your system `PATH`, or specified explicitly in code. Modern versions of Selenium handle browser and +driver installation for you with `Selenium Manager `_. You generally +don't have to worry about driver installation or configuration now that it's done for you when you instantiate a WebDriver. +Selenium Manager works with most supported platforms and browsers. If it doesn't meet your needs, you can still install and +specify browsers abnd drivers yourself. -Other supported browsers will have their own drivers available. Links to some of the more popular browser drivers follow. +Links to some of the more popular browser drivers: +--------------+-----------------------------------------------------------------------+ | **Chrome**: | https://chromedriver.chromium.org/downloads | @@ -62,59 +65,65 @@ Other supported browsers will have their own drivers available. Links to some of Example 0: ========== -* open a new Firefox browser -* load the page at the given URL +* launch a new Chrome browser +* load a web page +* close the browser .. code-block:: python from selenium import webdriver - browser = webdriver.Firefox() - browser.get('http://selenium.dev/') + + driver = webdriver.Chrome() + driver.get('https://selenium.dev/') + driver.quit() Example 1: ========== -* open a new Firefox browser -* load the Yahoo homepage -* search for "seleniumhq" +* launch a new Chrome browser +* load the Selenium documentation page +* find the "Webdriver" link +* click the "WebDriver" link * close the browser .. code-block:: python from selenium import webdriver from selenium.webdriver.common.by import By - from selenium.webdriver.common.keys import Keys - browser = webdriver.Firefox() - browser.get('http://www.yahoo.com') - assert 'Yahoo' in browser.title + driver = webdriver.Chrome() + + driver.get('https://selenium.dev/documentation') + assert 'Selenium' in driver.title - elem = browser.find_element(By.NAME, 'p') # Find the search box - elem.send_keys('seleniumhq' + Keys.RETURN) + elem = driver.find_element(By.ID, 'm-documentationwebdriver') + elem.click() + assert 'WebDriver' in driver.title - browser.quit() + driver.quit() Example 2: ========== -Selenium WebDriver is often used as a basis for testing web applications. Here is a simple example using Python's standard `unittest `_ library: +Selenium WebDriver is often used as a basis for testing web applications. Here is a simple example using Python's standard `unittest `_ library: .. code-block:: python import unittest from selenium import webdriver + class GoogleTestCase(unittest.TestCase): def setUp(self): - self.browser = webdriver.Firefox() - self.addCleanup(self.browser.quit) + self.driver = webdriver.Firefox() + self.addCleanup(self.driver.quit) def test_page_title(self): - self.browser.get('http://www.google.com') - self.assertIn('Google', self.browser.title) + self.driver.get('https://www.google.com') + self.assertIn('Google', self.driver.title) if __name__ == '__main__': unittest.main(verbosity=2) @@ -143,9 +152,9 @@ Contributing - Create a branch for your work - Ensure `tox` is installed (using a `virtualenv` is recommended) - - `python3.8 -m venv .venv && . .venv/bin/activate && pip install tox` + - Run: `python -m venv venv && venv/bin/activate && pip install tox` - After making changes, before committing execute `tox -e linting` - - If tox exits `0`, commit and push otherwise fix the newly introduced breakages. + - If tox exits `0`, commit and push. Otherwise fix the newly introduced styke violations. - `flake8` requires manual fixes - - `black` will often rewrite the breakages automatically, however the files are unstaged and should staged again. - - `isort` will often rewrite the breakages automatically, however the files are unstaged and should staged again. + - `black` will rewrite the violations automatically, however the files are unstaged and should staged again. + - `isort` will rewrite the viiolations automatically, however the files are unstaged and should staged again. From 630146f36cf6708c179c0739452e161f00626356 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Wed, 19 Mar 2025 19:33:12 -0400 Subject: [PATCH 07/12] [py] fix typos in README --- py/docs/source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/py/docs/source/index.rst b/py/docs/source/index.rst index 85929c4068e92..44e8efdca9eb0 100644 --- a/py/docs/source/index.rst +++ b/py/docs/source/index.rst @@ -48,7 +48,7 @@ executable was available on your system `PATH`, or specified explicitly in code. driver installation for you with `Selenium Manager `_. You generally don't have to worry about driver installation or configuration now that it's done for you when you instantiate a WebDriver. Selenium Manager works with most supported platforms and browsers. If it doesn't meet your needs, you can still install and -specify browsers abnd drivers yourself. +specify browsers and drivers yourself. Links to some of the more popular browser drivers: @@ -154,7 +154,7 @@ Contributing - Ensure `tox` is installed (using a `virtualenv` is recommended) - Run: `python -m venv venv && venv/bin/activate && pip install tox` - After making changes, before committing execute `tox -e linting` - - If tox exits `0`, commit and push. Otherwise fix the newly introduced styke violations. + - If tox exits `0`, commit and push. Otherwise fix the newly introduced style violations. - `flake8` requires manual fixes - `black` will rewrite the violations automatically, however the files are unstaged and should staged again. - - `isort` will rewrite the viiolations automatically, however the files are unstaged and should staged again. + - `isort` will rewrite the violations automatically, however the files are unstaged and should staged again. From ecb3b40ffd786ea4d8801089383a49de046e909e Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Wed, 19 Mar 2025 19:35:31 -0400 Subject: [PATCH 08/12] [py] Fix theme name --- py/docs/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/py/docs/README.rst b/py/docs/README.rst index a73e37715a362..a8ad3599ab121 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -39,8 +39,8 @@ dependencies. Then tox runs the ``sphinx-autogen`` command to generate autodoc s Then it runs ``sphinx-build`` to build the HTML 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 "sphinx_rtd_theme" theme (AKA "Read the Docs" theme) and -the the majority of the api documentation is autogenerated. There is plenty of information +here is that the docs are using the "sphinx-material" theme (AKA "Material for Sphinx" theme) +and the 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 reStructuredText and the Sphinx tool chain should be sufficient to contribute and develop the Python docs. From a78f4be2193a36e970289384bf8468f293c27d05 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Wed, 19 Mar 2025 19:40:48 -0400 Subject: [PATCH 09/12] [py] Update browser names in README --- py/docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/docs/source/index.rst b/py/docs/source/index.rst index 44e8efdca9eb0..b67b224d38c0f 100644 --- a/py/docs/source/index.rst +++ b/py/docs/source/index.rst @@ -21,7 +21,7 @@ The `selenium` package is used to automate web browser interaction from Python. | **IRC/Slack**: | `Selenium chat room `_ | +-----------------+--------------------------------------------------------------------------------------+ -Several browsers/drivers are supported (Firefox, Chrome, Internet Explorer), as well as the Remote protocol. +Several browsers/drivers are supported (Firefox, Chrome, Edge, Safari), as well as the Remote protocol. Supported Python Versions ========================= From 83e6d14df6a6a88e38ee1a9712ecc5cc216f7610 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Wed, 19 Mar 2025 21:43:00 -0400 Subject: [PATCH 10/12] [py] Add virtual env name --- py/docs/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/docs/README.rst b/py/docs/README.rst index a8ad3599ab121..f936eaa592780 100644 --- a/py/docs/README.rst +++ b/py/docs/README.rst @@ -17,7 +17,7 @@ Python documentation. .. code-block:: console - python3 -m venv + python3 -m venv venv source venv/bin/activate pip install tox git clone git@github.com:SeleniumHQ/selenium.git From 5e76faff29a4217885fabba41f22df37221eabf5 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Thu, 20 Mar 2025 12:32:20 -0400 Subject: [PATCH 11/12] [py] Change Sphinx version for docs --- py/docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/docs/requirements.txt b/py/docs/requirements.txt index b64127538fa49..39a1851859249 100644 --- a/py/docs/requirements.txt +++ b/py/docs/requirements.txt @@ -1,3 +1,3 @@ Jinja2==3.1.6 -Sphinx==8.2.3 +Sphinx==7.4.7 sphinx-material==0.0.36 From ab98ddd4f20778e24f0750531f03884928d81697 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Thu, 20 Mar 2025 12:43:11 -0400 Subject: [PATCH 12/12] [py] tiny fix in README --- py/docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/docs/source/index.rst b/py/docs/source/index.rst index b67b224d38c0f..4d81155e043e8 100644 --- a/py/docs/source/index.rst +++ b/py/docs/source/index.rst @@ -152,7 +152,7 @@ Contributing - Create a branch for your work - Ensure `tox` is installed (using a `virtualenv` is recommended) - - Run: `python -m venv venv && venv/bin/activate && pip install tox` + - Run: `python -m venv venv && source venv/bin/activate && pip install tox` - After making changes, before committing execute `tox -e linting` - If tox exits `0`, commit and push. Otherwise fix the newly introduced style violations. - `flake8` requires manual fixes