[DOCS] Add comprehensive README with troubleshooting and examples

[webbsssss]

• Added troubleshooting section for installation issues
• Added quick start code examples
• Helps new contributors get started quickly
• Perfect for GSoC contributors who are new to PSLab

Summary by Sourcery

Add a new README troubleshooting section to help users and contributors resolve common PSLab installation and connection issues.

Documentation:

• Document common PSLab installation errors and their resolutions in a troubleshooting section.
• Add guidance for resolving device connection issues when PSLab hardware is not detected.

[sourcery-ai]

Reviewer's Guide

Adds a new README for the pslab package focused on onboarding and support, including installation troubleshooting and basic connection guidance for PSLab hardware.

Flow diagram for troubleshooting installation and connection in README

flowchart TD
  A[Start: Attempt to use pslab] --> B{Does python3 command exist?}
  B -- Yes --> C[Run pip3 install -e .]
  B -- No --> D[Install Python 3 and pip3 using
sudo apt-get install python3 python3-pip]
  D --> C

  C --> E{Installation error?}
  E -- No --> F[Proceed to connect PSLab hardware]
  E -- ModuleNotFoundError: No module named pslab --> G[Re-run pip3 install -e . ensuring you are in project root]
  G --> E
  E -- Permission denied on Linux --> H[Run pip3 install --user -e . or use sudo]
  H --> E

  F --> I[Connect PSLab hardware via USB]
  I --> J[Run connection example]
  J --> K{Device found?}
  K -- Yes --> L[Use PSLab normally]
  K -- No --> M[Check USB ports with ls /dev/ttyUSB* on Linux]
  M --> N{Device appears in list?}
  N -- Yes --> J
  N -- No --> O[Inspect cable, port, or drivers outside of README scope]

Loading

File-Level Changes

Change	Details	Files
Introduce troubleshooting documentation for common installation problems when setting up PSLab in development mode.	Document resolution for ModuleNotFoundError by using editable installation via pip3 Provide guidance for handling permission errors on Linux with user or sudo installs Explain how to install Python 3 and pip3 when the python3 command is missing	pslab/README.md
Add documentation for basic hardware connection troubleshooting.	Describe steps to verify PSLab hardware is connected over USB Show how to check for the device on Linux via ls /dev/ttyUSB*	pslab/README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• The README currently starts with a very large block of blank lines; consider removing the leading whitespace so the content is visible immediately when opening the file.
• The fenced code block opened with markdown near the top of the file is never closed in the diff, which will break Markdown rendering; add the corresponding closing at the appropriate place.
• The troubleshooting apt-get instructions are Debian/Ubuntu-specific; it may be helpful to either note that explicitly or provide a more generic Python 3 installation hint for other platforms.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The README currently starts with a very large block of blank lines; consider removing the leading whitespace so the content is visible immediately when opening the file.
- The fenced code block opened with ```markdown near the top of the file is never closed in the diff, which will break Markdown rendering; add the corresponding closing ``` at the appropriate place.
- The troubleshooting `apt-get` instructions are Debian/Ubuntu-specific; it may be helpful to either note that explicitly or provide a more generic Python 3 installation hint for other platforms.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[webbsssss]

Removed leading blank lines.

Closed the markdown code block.

Added Debian/Ubuntu, macOS, and generic Python 3 installation notes