[py] Configure readthedocs publishing for Python API docs

[cgoldberg]

User description

💥 What does this PR do?

supersedes #15611

This PR fixes the publishing of the Python API docs at readthedocs.com. This has been broken since Selenium version 4.14.

The docs get published with every commit to selenium trunk (I think). The job is configured at: https://app.readthedocs.org/projects/selenium-python-api-docs (this account is managed by @diemol)

Once the job runs, docs are published to: https://selenium-python-api-docs.readthedocs.io

I tested this configuration from my own account at readthedocs.com pointing to my fork of the selenium repo, and it worked fine.

Note: I don't think the readthedocs job is configured to build Pull Requests, so this won't be triggered until it lands in trunk.

---

PR Type

Bug fix, Documentation

---

Description

• Updated Read the Docs configuration for Python API documentation.

• Moved .readthedocs.yaml to py/docs directory.

• Enhanced Python API documentation with updated links and structure.

• Added support for newer Python versions and updated build tools.

---

Changes walkthrough 📝

	Relevant files
Configuration changes	.readthedocs.yaml Removed outdated Read the Docs configuration.                        .readthedocs.yaml Removed the old Read the Docs configuration file. +0/-32    .readthedocs.yaml Added updated Read the Docs configuration file.                    py/docs/.readthedocs.yaml Added a new Read the Docs configuration file. Updated build tools and Python version to latest. Added commands for building and publishing documentation. +21/-0
Documentation	index.rst Enhanced Python API documentation content.                              py/docs/source/index.rst Updated API documentation links and structure. Added supported browsers and Python versions. Improved contributing guidelines for clarity. +42/-21

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-merge-pro]

PR Reviewer Guide 🔍

(Review updated until commit f79b87e)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Path Verification The build commands use absolute paths like 'py/docs/requirements.txt' and 'py/requirements.txt'. Verify these paths are correct relative to where RTD executes the commands, as path resolution might differ in the RTD environment. - pip install -r py/docs/requirements.txt - pip install -r py/requirements.txt - PYTHONPATH=py sphinx-autogen -o $READTHEDOCS_OUTPUT/html py/docs/source/api.rst - sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html

[qodo-merge-pro]

PR Code Suggestions ✨

Latest suggestions up to 88deeb7

Category	Suggestion	Impact
Possible issue	Fix relative paths The build commands are using absolute paths that might cause issues in the Read the Docs environment. The paths should be relative to the configuration file location to ensure proper execution. py/docs/.readthedocs.yaml [10-18] build: os: ubuntu-24.04 tools: python: "3.11" commands: - - pip install -r py/docs/requirements.txt - - pip install -r py/requirements.txt - - 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 + - pip install -r ../requirements.txt + - pip install -r requirements.txt + - PYTHONPATH=.. sphinx-autogen -o $READTHEDOCS_OUTPUT/html source/api.rst + - PYTHONPATH=.. sphinx-build -b html -d build/doctrees source $READTHEDOCS_OUTPUT/html Apply this suggestion Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential issue with absolute paths in the build commands. Using relative paths instead of absolute paths is more maintainable and less error-prone in the Read the Docs environment, especially since the configuration file has been moved to a subdirectory.	Medium
Update

---

Previous suggestions

✅ Suggestions up to commit adb498d

Category	Suggestion	Impact
Possible issue	Fix relative path references The build commands are using absolute paths that might cause issues in the ReadTheDocs environment. The paths should be relative to the repository root, but the configuration file is now in a subdirectory. Consider using environment variables or adjusting paths to ensure they're correctly resolved. py/docs/.readthedocs.yaml [10-18] build: os: ubuntu-24.04 tools: python: "3.11" commands: - - pip install -r py/docs/requirements.txt - - pip install -r py/requirements.txt - - 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 + - pip install -r ../../py/docs/requirements.txt + - pip install -r ../../py/requirements.txt + - cd ../.. && PYTHONPATH=py sphinx-autogen -o $READTHEDOCS_OUTPUT/html py/docs/source/api.rst + - cd ../.. && PYTHONPATH=py sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a critical issue with path references in the ReadTheDocs configuration. Since the file has been moved to a subdirectory, the absolute paths would fail to resolve correctly, potentially breaking the documentation build process.	Medium
General	✅ Fix grammatical errors Suggestion Impact: The commit implemented exactly the grammatical correction suggested, adding the missing 'be' in 'should be staged again' for both the black and isort instructions code diff: - - `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 + - `black` will rewrite the violations automatically, however the files are unstaged and should be staged again + - `isort` will rewrite the violations automatically, however the files are unstaged and should be staged again There's a grammatical error in the instructions about staging files after running black and isort. The phrase "should staged again" is incorrect and could confuse contributors. py/docs/source/index.rst [178-180] - `flake8` requires manual fixes -- `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 +- `black` will rewrite the violations automatically, however the files are unstaged and should be staged again +- `isort` will rewrite the violations automatically, however the files are unstaged and should be staged again [Suggestion has been applied] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies and fixes a grammatical error in the contributing instructions, changing "should staged again" to "should be staged again". While not affecting functionality, this improves clarity and professionalism of the documentation.	Low

✅ Suggestions up to commit a45492e

Category	Suggestion	Impact
General	✅ Use specific Python version Suggestion Impact: The commit directly implemented the suggestion by changing the Python version from 'latest' to '3.11' in the .readthedocs.yaml file code diff: - python: "latest" + python: "3.11" Using "latest" for Python version can lead to unexpected build failures when new Python versions are released. Specify a concrete Python version (like "3.11") to ensure build stability and reproducibility. py/docs/.readthedocs.yaml [10-18] build: os: ubuntu-24.04 tools: - python: "latest" + python: "3.11" commands: - pip install -r py/docs/requirements.txt - pip install -r py/requirements.txt - 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 Suggestion importance[1-10]: 7 __ Why: Using a specific Python version instead of "latest" is a good practice for build stability and reproducibility. This change would prevent potential issues when new Python versions are released that might introduce compatibility problems.	Medium

✅ Suggestions up to commit f79b87e

Category	Suggestion	Impact
Possible issue	✅ Add PYTHONPATH to sphinx-build Suggestion Impact: The commit implemented exactly what was suggested - adding the PYTHONPATH=py environment variable to the sphinx-build command to prevent potential import errors during documentation building code diff: - - sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html + - PYTHONPATH=py sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html The PYTHONPATH environment variable is set only for the sphinx-autogen command but not for the sphinx-build command. This could lead to import errors during documentation building if the Python modules need to be imported from the py directory. py/docs/.readthedocs.yaml [10-18] build: os: ubuntu-24.04 tools: python: "latest" commands: - pip install -r py/docs/requirements.txt - pip install -r py/requirements.txt - PYTHONPATH=py sphinx-autogen -o $READTHEDOCS_OUTPUT/html py/docs/source/api.rst - - sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html + - PYTHONPATH=py sphinx-build -b html -d build/docs/doctrees py/docs/source $READTHEDOCS_OUTPUT/html [Suggestion has been applied] Suggestion importance[1-10]: 8 __ Why: This suggestion addresses a potential build failure issue. Setting PYTHONPATH for sphinx-autogen but not for sphinx-build could cause import errors during documentation generation since sphinx-build also needs to access Python modules in the py directory.	Medium