Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleaned up Py doc sphinx warnings/errors and added README #14191

Merged
merged 3 commits into from
Nov 8, 2024

Conversation

emanlove
Copy link
Contributor

@emanlove emanlove commented Jun 26, 2024

User description

Fixed Py documentation issues and added README focused on Py docs

Description

  • Cleaned up a few doc strings fixing various sphinx build error and warnings
  • Minor spelling corrections (although I am sure I made plenty of my own in the new readme ..)
  • Added py/docs/README.rst leaving some instructions for the next person

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist

  • I have read the contributing document.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

PR Type

Bug fix, Documentation


Description

  • Fixed various Sphinx warnings and errors in Python docstrings across multiple files.
  • Corrected spelling and formatting issues in docstrings to improve readability.
  • Added a new README file for Python documentation with detailed build and contribution instructions.
  • Listed known documentation issues and provided guidance on resolving them.

Changes walkthrough 📝

Relevant files
Bug fix
webdriver.py
Fix Sphinx warnings/errors in Chromium WebDriver docstrings

py/selenium/webdriver/chromium/webdriver.py

  • Fixed formatting issues in docstrings to resolve Sphinx
    warnings/errors.
  • Improved readability of docstring content.
  • +4/-5     
    print_page_options.py
    Correct spelling and formatting in PrintOptions docstrings

    py/selenium/webdriver/common/print_page_options.py

  • Corrected spelling errors in docstrings.
  • Fixed minor formatting issues in docstrings.
  • +2/-2     
    virtual_authenticator.py
    Fix indentation in VirtualAuthenticator docstrings             

    py/selenium/webdriver/common/virtual_authenticator.py

  • Fixed indentation issues in docstrings to resolve Sphinx
    warnings/errors.
  • +5/-5     
    relative_locator.py
    Improve readability and formatting in RelativeLocator docstrings

    py/selenium/webdriver/support/relative_locator.py

  • Added missing blank lines for better readability in docstrings.
  • Fixed minor formatting issues in docstrings.
  • +7/-6     
    Documentation
    README.rst
    Add README for Python documentation with build instructions

    py/docs/README.rst

  • Added new README file for Python documentation.
  • Included instructions for building and contributing to the
    documentation.
  • Listed known documentation issues and how to resolve them.
  • +71/-0   

    💡 PR-Agent usage:
    Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

    - Cleaned up various sphinx build error and warnings
    - Added py/docs/README.rst leaving some instructions for the next person
    Copy link
    Contributor

    PR Reviewer Guide 🔍

    ⏱️ Estimated effort to review [1-5] 2
    🧪 Relevant tests No
    🔒 Security concerns No
    ⚡ Key issues to review Spelling Error:
    In py/selenium/webdriver/common/virtual_authenticator.py, the word "intital" should be corrected to "initial".
    Consistency in Documentation:
    Ensure consistent formatting in documentation comments across all modified files. For example, the use of bullet points in argument descriptions should be consistently applied.

    Copy link
    Contributor

    qodo-merge-pro bot commented Jun 26, 2024

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Typo
    Correct a typo in the docstring for better clarity

    Correct the typo in the docstring from "intital" to "initial" for better clarity and
    professionalism.

    py/selenium/webdriver/common/virtual_authenticator.py [98]

    -- sign_count (int): intital value for a signature counter.
    +- sign_count (int): initial value for a signature counter.
     
    • Apply this suggestion
    Suggestion importance[1-10]: 6

    Why: The suggestion correctly identifies and fixes a typo in the docstring, which improves the professionalism of the documentation.

    6
    Correct a typo in the README documentation for better readability

    Correct the typo "contibuting" to "contributing" to improve the professionalism and
    readability of the documentation.

    py/docs/README.rst [67]

    -Some steps for contibuting to the Python documentation ..
    +Some steps for contributing to the Python documentation ..
     
    • Apply this suggestion
    Suggestion importance[1-10]: 6

    Why: This suggestion correctly identifies a typo in the README, which helps in maintaining the professionalism of the documentation.

    6
    Style
    ✅ Remove trailing whitespace to maintain code cleanliness
    Suggestion Impact:The commit removed trailing whitespace at the end of lines, which aligns with the suggestion to maintain code cleanliness.

    code diff:

    -        
    +
             elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
    -        
    +

    Remove the trailing whitespace at the end of lines to maintain code cleanliness and adhere
    to style guidelines.

    py/selenium/webdriver/support/relative_locator.py [66-68]

    -+        
     elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
    -+
     
    • Apply this suggestion
    Suggestion importance[1-10]: 5

    Why: The suggestion is correct in aiming to remove unnecessary whitespace, which aligns with good coding practices, though it's a relatively minor improvement.

    5
    Readability
    Improve readability of the example dictionary in the docstring by using consistent spacing around colons

    The example dictionary in the docstring should use consistent spacing around the colons
    for better readability and to follow Python's PEP 8 style guide.

    py/selenium/webdriver/chromium/webdriver.py [82]

    -For example:     {'latency': 4, 'download_throughput': 2, 'upload_throughput': 2, 'offline': False}
    +For example: {'latency': 4, 'download_throughput': 2, 'upload_throughput': 2, 'offline': False}
     
    • Apply this suggestion
    Suggestion importance[1-10]: 4

    Why: The suggestion correctly identifies a minor style improvement in the docstring for readability. However, it's a low-impact change.

    4

    @VietND96 VietND96 merged commit d5ab5ff into SeleniumHQ:trunk Nov 8, 2024
    14 checks passed
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    3 participants