[py] Update Python documentation (modernization)

Author: cgoldberg

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 <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 instructions above.
 - Try to resolve any warnings/errors.

py/docs/requirements.txt

@@ -1,2 +1,3 @@
 Jinja2==3.1.6
 Sphinx==8.2.3
+sphinx-material==0.0.36

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

py/docs/source/conf.py

@@ -14,7 +14,9 @@ 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>`_                   |
 +-----------------+--------------------------------------------------------------------------------------+
@@ -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 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 <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 && 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.