[py] Auto-generate Python API docs from code (SeleniumHQ#15822)

* Update the Python documentation build process so API documentation is auto-generated from code
* Added new script (./py/generate_api_module_listing.py) that scans the codebase for Python modules and generates a new api.rst file. This file is later used by sphinx-autogen to generate sphinx autodoc stub pages used in the Python API documentation.
* Update tox.ini and readthedocs.yaml to call the script when building docs

Author: cgoldberg

.gitignore

@@ -76,6 +76,7 @@ py/selenium/webdriver/remote/isDisplayed.js
 py/docs/build/
 py/docs/source/**/*
 !py/docs/source/conf.py
+!py/docs/source/*.rst
 py/build/
 py/LICENSE
 py/pytestdebug.log

py/docs/.readthedocs.yaml

@@ -10,10 +10,11 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.12"
   commands:
     - pip install -r py/docs/requirements.txt
     - pip install -r py/requirements.txt
+    - PYTHONPATH=py python3 py/generate_api_module_listing.py
     - PYTHONPATH=py sphinx-autogen -o $READTHEDOCS_OUTPUT/html py/docs/source/api.rst
     - PYTHONPATH=py sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html
 

py/docs/Makefile

@@ -49,22 +49,14 @@ and develop the Python docs.
 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.
+After using the tox environment above, you can clean up the build assets by deleting the ``build``
+directory in the root of the repo. Note that tox caches parts of the build and recognizes changes
+to speed up the build. To start fresh, delete the ``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>`_
-
 We are working through the Sphinx build warnings and errors, trying to clean up both the syntax and
 the build.