Updates the py api doc build (SeleniumHQ#14173)

* Added requirements.txt to doc build environment

For the API documentation as sphinx autogenerates the
api docs from the code it needs the dependent Python
packages. This change adds those to the tox docs build
environment.

* Updated Sphinx version within docs/requirements.txt

Bring Sphinx version up to the latest Python 3.8 suported version,
v7.1.2. This change was made within py/docs/requirements.txt. It
should be noted that there is a seperate version requirement given
within py/tox.ini which I need to test and see which one is grabed
using the selenium build process. (I supsect it will be the one
within py/tox.ini.)

* Added step in api doc build to regenerate the autodoc stub pages

Instead of using the commited stub files which contain "pre-compiled"
outlines for the api doc this will regenrate them. It should be noted
this might add some time to the build process so a future change might
be to see how store and update either commited files or previous
build artifacts.

I also and working though the output directory which is currently set to
`-o docs/source`. This seem to dump all the sub files into the main source
directory insted of neatly organied into child directories. Going to try
to reowrk this but wanted to commit so as not to lose how I did this the
first time ;)

* wip adding new files in api.rst

Credit goes to @iampopovich for these changes

* wip alphabetical order in api.rst

Credit goes to @iampopovich for these changes

* Removed previous generated api doc stub files

Prefer instead to auto-generate these as part of the build.
Also ignore those sub-directories.

* Updated the tox api doc build steps

- Use the docs/requirements.txt file instead of repeating the build
  versions for jinja and sphinx
- Removed the output directory option on sphinx-autogen as that was
  putting everything in a flat directory structure at the root instead
  of the well organized folders

Author: emanlove

.gitignore

@@ -74,6 +74,7 @@ py/selenium/webdriver/remote/findElements.js
 py/selenium/webdriver/remote/getAttribute.js
 py/selenium/webdriver/remote/isDisplayed.js
 py/docs/build/
+py/docs/source/**/*
 py/build/
 py/LICENSE
 py/pytestdebug.log

py/docs/requirements.txt

@@ -1,2 +1,2 @@
 Jinja2==3.1.4
-Sphinx==1.8.2
+Sphinx==7.1.2

py/docs/source/api.rst

@@ -24,26 +24,32 @@ Webdriver.common
    selenium.webdriver.common.alert
    selenium.webdriver.common.by
    selenium.webdriver.common.desired_capabilities
+   selenium.webdriver.common.driver_finder
    selenium.webdriver.common.keys
    selenium.webdriver.common.log
+   selenium.webdriver.common.options
    selenium.webdriver.common.print_page_options
    selenium.webdriver.common.proxy
-   selenium.webdriver.common.utils
+   selenium.webdriver.common.selenium_manager
    selenium.webdriver.common.service
-   selenium.webdriver.common.options
    selenium.webdriver.common.timeouts
+   selenium.webdriver.common.utils
+   selenium.webdriver.common.virtual_authenticator
    selenium.webdriver.common.window
    selenium.webdriver.common.actions.action_builder
    selenium.webdriver.common.actions.input_device
    selenium.webdriver.common.actions.interaction
    selenium.webdriver.common.actions.key_actions
    selenium.webdriver.common.actions.key_input
    selenium.webdriver.common.actions.mouse_button
-   selenium.webdriver.common.actions.pointer_input
    selenium.webdriver.common.actions.pointer_actions
-   selenium.webdriver.common.actions.wheel_input
+   selenium.webdriver.common.actions.pointer_input
    selenium.webdriver.common.actions.wheel_actions
-   selenium.webdriver.common.virtual_authenticator
+   selenium.webdriver.common.actions.wheel_input
+   selenium.webdriver.common.bidi.cdp
+   selenium.webdriver.common.bidi.console
+   selenium.webdriver.common.bidi.script
+   selenium.webdriver.common.bidi.session
 
 Webdriver.support
 -----------------
@@ -55,9 +61,11 @@ Webdriver.support
    selenium.webdriver.support.abstract_event_listener
    selenium.webdriver.support.color
    selenium.webdriver.support.event_firing_webdriver
+   selenium.webdriver.support.events
    selenium.webdriver.support.expected_conditions
    selenium.webdriver.support.relative_locator
    selenium.webdriver.support.select
+   selenium.webdriver.support.ui
    selenium.webdriver.support.wait
 
 Webdriver.chrome
@@ -68,6 +76,7 @@ Webdriver.chrome
    :toctree: webdriver_chrome
 
    selenium.webdriver.chrome.options
+   selenium.webdriver.chrome.remote_connection
    selenium.webdriver.chrome.service
    selenium.webdriver.chrome.webdriver
 
@@ -79,8 +88,8 @@ Webdriver.chromium
    :toctree: webdriver_chromium
 
    selenium.webdriver.chromium.options
-   selenium.webdriver.chromium.service
    selenium.webdriver.chromium.remote_connection
+   selenium.webdriver.chromium.service
    selenium.webdriver.chromium.webdriver
 
 Webdriver.edge
@@ -91,6 +100,7 @@ Webdriver.edge
    :toctree: webdriver_edge
 
    selenium.webdriver.edge.options
+   selenium.webdriver.edge.remote_connection
    selenium.webdriver.edge.service
    selenium.webdriver.edge.webdriver
 
@@ -101,13 +111,12 @@ Webdriver.firefox
 .. autosummary::
    :toctree: webdriver_firefox
 
-   selenium.webdriver.firefox.extension_connection
-   selenium.webdriver.firefox.remote_connection
    selenium.webdriver.firefox.firefox_binary
-   selenium.webdriver.firefox.options
    selenium.webdriver.firefox.firefox_profile
-   selenium.webdriver.firefox.webdriver
+   selenium.webdriver.firefox.options
+   selenium.webdriver.firefox.remote_connection
    selenium.webdriver.firefox.service
+   selenium.webdriver.firefox.webdriver
 
 Webdriver.ie
 ------------
@@ -127,18 +136,19 @@ Webdriver.remote
 .. autosummary::
    :toctree: webdriver_remote
 
-   selenium.webdriver.remote.command
    selenium.webdriver.remote.bidi_connection
+   selenium.webdriver.remote.command
    selenium.webdriver.remote.errorhandler
+   selenium.webdriver.remote.file_detector
    selenium.webdriver.remote.mobile
    selenium.webdriver.remote.remote_connection
+   selenium.webdriver.remote.script_key
    selenium.webdriver.remote.shadowroot
+   selenium.webdriver.remote.switch_to
    selenium.webdriver.remote.utils
    selenium.webdriver.remote.webdriver
    selenium.webdriver.remote.webelement
-   selenium.webdriver.remote.file_detector
-   selenium.webdriver.remote.script_key
-   selenium.webdriver.remote.switch_to
+   selenium.webdriver.remote.websocket_connection
 
 Webdriver.safari
 ----------------
@@ -148,10 +158,22 @@ Webdriver.safari
   :toctree: webdriver_safari
 
   selenium.webdriver.safari.options
+  selenium.webdriver.safari.permissions
   selenium.webdriver.safari.remote_connection
   selenium.webdriver.safari.service
   selenium.webdriver.safari.webdriver
 
+Webdriver.wpewebkit
+-------------------
+
+.. currentmodule:: selenium.webdriver.wpewebkit
+.. autosummary::
+  :toctree: webdriver_wpewebkit
+
+  selenium.webdriver.wpewebkit.options
+  selenium.webdriver.wpewebkit.service
+  selenium.webdriver.wpewebkit.webdriver
+
 Webdriver.webkitgtk
 -------------------