diff --git a/py/docs/README.rst b/py/docs/README.rst index 8b58a410e00ff..f936eaa592780 100644 --- a/py/docs/README.rst +++ b/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 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 + 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 `_ +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 =========================== + 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 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 +- 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 --git a/py/docs/requirements.txt b/py/docs/requirements.txt index 37102cb397363..39a1851859249 100644 --- a/py/docs/requirements.txt +++ b/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 --git a/py/docs/selenium_logo_small.png b/py/docs/selenium_logo_small.png new file mode 100644 index 0000000000000..8028a2be827d0 Binary files /dev/null and b/py/docs/selenium_logo_small.png differ diff --git a/py/docs/source/conf.py b/py/docs/source/conf.py index ce8b34a8c6d92..41c70252b33d4 100644 --- a/py/docs/source/conf.py +++ b/py/docs/source/conf.py @@ -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 --git a/py/docs/source/index.rst b/py/docs/source/index.rst old mode 100755 new mode 100644 index 2133a11e05949..4d81155e043e8 --- a/py/docs/source/index.rst +++ b/py/docs/source/index.rst @@ -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 `_ | +-----------------+--------------------------------------------------------------------------------------+ -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 `_ 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 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 `_ 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 && 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 --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