[py] Update Python documentation (modernization) (#15459)

* [py] Remove blank line in tox.ini

* [py] Update instructions for docs

* [py] Bump Sphinx and Jinja2 versions for building docs

* [py] Change permissions of index.rst

* [py] Update instructions for building docs

* [py] Update Python documentation (modernization)

* [py] fix typos in README

* [py] Fix theme name

* [py] Update browser names in README

* [py] Add virtual env name

* [py] Change Sphinx version for docs

* [py] tiny fix in README

Author: cgoldberg

Diff for: py/docs/README.rst

@@ -11,61 +11,72 @@ 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 -e docs``, building the
+Python documentation.
 
 .. code-block:: console
 
-    virtualenv test-py38-env
-    source test-py38-env/bin/activate
+    python3 -m venv venv
+    source venv/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
+    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.
 
-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.
+
+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-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.
+
+
+To clean up the build assets and tox cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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 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
-soley from the code if possible. This is being tracked in `#14178 <https://github.com/SeleniumHQ/selenium/issues/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 <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
+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 <https://github.com/SeleniumHQ/selenium/blob/trunk/CONTRIBUTING.md>`_.
 
-Some steps for contibuting to the Python documentation ..
+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.
+- Check out changes locally using instructions above.
+- Try to resolve any warnings/errors.
+  - If too arduous, either ask for help or add to the list of known issues.
+- If this process is updated, please update this doc as well to help the next person.

Diff for: py/docs/requirements.txt

@@ -1,2 +1,3 @@
-Jinja2==3.1.5
-Sphinx==7.1.2
+Jinja2==3.1.6
+Sphinx==7.4.7
+sphinx-material==0.0.36

Diff for: py/docs/selenium_logo_small.png

@@ -49,7 +49,7 @@
 
 # General information about the project.
 project = 'Selenium'
-copyright = '2009-2024 Software Freedom Conservancy'
+copyright = '2009-2025 Software Freedom Conservancy'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -97,9 +97,8 @@
 
 # -- Options for HTML output ---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'default'
+# The theme to use for HTML and HTML Help pages
+html_theme = 'sphinx_material'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -118,7 +117,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../selenium_logo_small.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -146,13 +145,13 @@
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+html_split_index = True
 
 # If true, links to the reST sources are added to the pages.
 html_show_sourcelink = True

Diff for: py/docs/source/conf.py

@@ -14,12 +14,14 @@ 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                                   |
 +-----------------+--------------------------------------------------------------------------------------+
 | **IRC/Slack**:  | `Selenium chat room <https://www.selenium.dev/support/#ChatRoom>`_                   |
 +-----------------+--------------------------------------------------------------------------------------+
 
-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
 =========================
@@ -33,21 +35,22 @@ If you have `pip <https://pip.pypa.io/>`_ on your system, you can simply install
 
     pip install -U selenium
 
-Alternately, you can download the source distribution from `PyPI <https://pypi.org/project/selenium/#files>`, unarchive it, and run::
-
-    python -m pip install .
-
-Note: You may want to consider using `virtualenv <http://www.virtualenv.org/>`_ to create isolated Python environments.
+You may want to consider using a `virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments>`_
+to create isolated Python environments.
 
 Drivers
 =======
 
-Selenium requires a driver to interface with the chosen browser. Firefox,
-for example, requires `geckodriver <https://github.com/mozilla/geckodriver/releases>`_, 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 <https://www.selenium.dev/documentation/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 and 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 <http://docs.python.org/3/library/unittest.html>`_ library:
+Selenium WebDriver is often used as a basis for testing web applications. Here is a simple example using Python's standard `unittest <http://docs.python.org/3/library/unittest.html>`_ 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 && 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 breakages.
+ - If tox exits `0`, commit and push. Otherwise fix the newly introduced style 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 violations automatically, however the files are unstaged and should staged again.

Diff for: py/docs/source/index.rst

@@ -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