[py] Configure readthedocs publishing for Python API docs by cgoldberg · Pull Request #15614 · SeleniumHQ/selenium

cgoldberg · 2025-04-11T00:31:42Z

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-code-review · 2025-04-11T00:31:58Z

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-code-review · 2025-04-11T00:32:08Z

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

.readthedocs.yaml

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

cgoldberg added 11 commits April 10, 2025 19:17

Update readthedocs configuration

f3aadf4

Update readthedocs config

b3473e9

Update readthedocs config

90a70d3

Update readthedocs config

497eaa5

Update readthedocs config

72f8a0f

Update readthedocs config

590eb5c

Update readthedocs config

36d705a

Update readthedocs config

0b358ca

Update readthedocs config

16e1116

Update readthedocs config

6bb3a36

Update readthedocs config amd change api doc link

98c1bc6

selenium-ci added the C-py Python Bindings label Apr 11, 2025

qodo-code-review bot added Review effort 1/5 and removed C-py Python Bindings labels Apr 11, 2025

cgoldberg mentioned this pull request Apr 11, 2025

Remove .readthedocs.yaml #15611

Closed

qodo-code-review bot reviewed Apr 11, 2025

View reviewed changes

.readthedocs.yaml Outdated Show resolved Hide resolved

cgoldberg and others added 2 commits April 10, 2025 20:54

Update .readthedocs.yaml

3f63d78

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

Update readthedocs config

bfc0c2c

diemol approved these changes Apr 11, 2025

View reviewed changes

cgoldberg added 2 commits April 11, 2025 12:24

Move readthedocs config file to python directory

4f25b5a

Update Python docs

f79b87e

cgoldberg closed this Apr 11, 2025

cgoldberg deleted the readthedocs-config branch April 11, 2025 17:26

cgoldberg restored the readthedocs-config branch April 11, 2025 17:27

cgoldberg reopened this Apr 11, 2025

qodo-code-review bot added Review effort 2/5 and removed Review effort 1/5 labels Apr 11, 2025

Fix index.rst

0adc5d8

cgoldberg added 6 commits April 11, 2025 13:35

Update links to drivers in docs

ad71454

Minor updates to Python docs

e8af501

Update environment variable

a45492e

Build docs with Python 3.13

adb498d

Fix grammatical error

88deeb7

Merge branch 'trunk' into readthedocs-config

30dad06

cgoldberg merged commit f629044 into SeleniumHQ:trunk Apr 11, 2025
9 checks passed

cgoldberg deleted the readthedocs-config branch April 11, 2025 17:50

garrettgregor mentioned this pull request May 3, 2025

build(deps-dev): bump selenium-webdriver from 4.31.0 to 4.32.0 garrettgregor/quote-editor#45

Merged

This was referenced Sep 12, 2025

Bump the functionaltests group with 8 updates israurreacarballo/DORA#196

Closed

Bump coverlet.collector and 5 others israurreacarballo/DORA#201

Closed

Bump the selenium group with 2 updates 7474/SRC#677

Merged

This was referenced Sep 19, 2025

Bump coverlet.collector and 5 others israurreacarballo/DORA#217

Closed

Bump the functionaltests group with 9 updates israurreacarballo/DORA#225

Closed

Bump coverlet.collector and 5 others israurreacarballo/DORA#228

Closed

dependabot bot mentioned this pull request Oct 24, 2025

Bump Selenium.WebDriver from 4.7.0 to 4.37.0 javiertuya/selema#945

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[py] Configure readthedocs publishing for Python API docs#15614

[py] Configure readthedocs publishing for Python API docs#15614
cgoldberg merged 22 commits intoSeleniumHQ:trunkfrom
cgoldberg:readthedocs-config

cgoldberg commented Apr 11, 2025 •

edited by qodo-code-review bot

Loading

Uh oh!

qodo-code-review bot commented Apr 11, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Apr 11, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

cgoldberg commented Apr 11, 2025 • edited by qodo-code-review bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

💥 What does this PR do?

PR Type

Description

Changes walkthrough 📝

Uh oh!

qodo-code-review bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Reviewer Guide 🔍

(Review updated until commit f79b87e)

Uh oh!

qodo-code-review bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Previous suggestions

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cgoldberg commented Apr 11, 2025 •

edited by qodo-code-review bot

Loading

qodo-code-review bot commented Apr 11, 2025 •

edited

Loading

(Review updated until commit `f79b87e`)

qodo-code-review bot commented Apr 11, 2025 •

edited

Loading