Documentation - "Bookworm"

[bsimmo]

Over the past months more and more people are having problems using gpiozero, it is talked about on the main Pi Forum and other places.
Having a look at the first steps/setup etc, it really could do with some updates and hand holding for people.
It is pretty much 'bookworm' that has caused this, hence the title.
While I know it has no problems if you just use it with nothing else added via either the Terminal or Thonny
If the user wants to add their own module and use gpiozero then things start to go wrong...

I guide to the different ways it can be setup might be useful as a place to point people to.

The RPi website / pip install recommends venv, so I believe it should be based around that.
Probably providing venv private/local install and use, but also using the public/system-widey-OS version too.

---

Of course as lgpio is not part of the requirement (nor the other ones). So they run a program and it complains...

It doesn't work.
So people get confused.

---

Now since pypi / pip version of lgpio doesn't work if they get that far it causes yet another headache and everyone is stuck and you give up and go make a coffee, get some water if your a student, your lesson is ruined etc... This last part is out of the scope of gpiozero though, hopefully is gets fixed.

---

Now you head the warning given by pip and realise you have to break system packages, hoping nothing burns and destroys the OS, so you edit pyenv.cfg and add the line
include-system-site-packages = true

Restart the venv
Remember you need to pip uninstall gpiozero becasue it still moans at you.
And then it all works ok for now.

[lurch]

According to raspberrypi/linux#6037 (comment) lgpio now works inside virtualenvs 🎉