Merge pull request #3851 from raspberrypi/develop

Roll out latest changes to production

Gemfile

@@ -11,7 +11,7 @@ source "https://rubygems.org"
 gem "jekyll", "~> 4.3.4"
 
 # This is the default theme for new Jekyll sites. You may change this to anything you like.
-gem "minima", "~> 2.0"
+gem "minima", "~> 2.5"
 
 # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
 # uncomment the line below. To upgrade, run `bundle update github-pages`.

Gemfile.lock

@@ -3,7 +3,7 @@ GEM
   specs:
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
-    asciidoctor (2.0.20)
+    asciidoctor (2.0.23)
     asciidoctor-tabs (1.0.0.beta.6)
       asciidoctor (>= 2.0.0, < 3.0.0)
     bigdecimal (3.1.8)
@@ -44,7 +44,7 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.0.0)
       sass-embedded (~> 1.54)
-    jekyll-seo-tag (2.7.1)
+    jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
@@ -58,7 +58,7 @@ GEM
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
     mini_portile2 (2.8.7)
-    minima (2.5.1)
+    minima (2.5.2)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
@@ -74,7 +74,7 @@ GEM
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     rexml (3.3.7)
-    rouge (4.3.0)
+    rouge (4.4.0)
     safe_yaml (1.0.5)
     sass-embedded (1.78.0)
       google-protobuf (~> 4.27)
@@ -89,7 +89,7 @@ GEM
     tilt (2.3.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    tzinfo-data (1.2024.1)
+    tzinfo-data (1.2024.2)
       tzinfo (>= 1.0.0)
     unicode-display_width (2.6.0)
     wdm (0.2.0)
@@ -104,7 +104,7 @@ DEPENDENCIES
   jekyll (~> 4.3.4)
   jekyll-asciidoc
   jekyll-feed (~> 0.17)
-  minima (~> 2.0)
+  minima (~> 2.5)
   nokogiri (~> 1.16)
   slim (~> 5.2.1)
   thread_safe (~> 0.3.5)

documentation/asciidoc/computers/os/using-python.adoc

@@ -59,117 +59,126 @@ Python users have long dealt with conflicts between OS package managers like `ap
 
 Starting in Raspberry Pi OS _Bookworm_, packages installed via `pip` _must be installed into a Python virtual environment_ (``venv``). A virtual environment is a container where you can safely install third-party modules so they won't interfere with your system Python.
 
-==== Use pip with virtual environments
+==== Use `pip` with virtual environments
 
-To use a virtual environment, create a container to store the environment. There are several ways you can do this depending on how you want to work with Python.
-
-Run the following command to create a virtual environment configuration folder, replacing `<env-name>` with the name you would like to use for the virtual environment (e.g. `env`):
+To use a virtual environment, create a container to store the environment. There are several ways you can do this depending on how you want to work with Python:
 
+[tabs]
+======
+per-project environments::
++
+Many users create separate virtual environments for each Python project. Locate the virtual environment in the root folder of each project, typically with a shared name like `env`. Run the following command from the root folder of each project to create a virtual environment configuration folder:
++
 [source,console]
 ----
-$ python -m venv <env-name>
+$ python -m venv env
 ----
-
-TIP: Pass the `--system-site-packages` flag before the folder name to preload all of the currently installed packages in your system Python installation into the virtual environment.
-
-Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment:
-
++
+Before you work on a project, run the following command from the root of the project to start using the virtual environment:
++
 [source,console]
 ----
-$ source <env-name>/bin/activate
+$ source env/bin/activate
 ----
-
++
 You should then see a prompt similar to the following:
-
-[source,console?prompt=(<env-name>) $]
-----
-(<env-name>) $
-----
-
-The `(<env-name>)` command prompt prefix indicates that the current terminal session is in a virtual environment named `<env-name>`.
-
-To check that you're in a virtual environment, use `pip list` to view the list of installed packages:
-
-[source,console?prompt=(<env-name>) $]
++
+[source,console?prompt=(env) $]
 ----
-(<env-name>) $ pip list
-Package    Version
----------- -------
-pip        23.0.1
-setuptools 66.1.1
+(env) $
 ----
-
-The list should be much shorter than the list of packages installed in your system Python. You can now safely install packages with `pip`. Any packages you install with `pip` while in a virtual environment only install to that virtual environment. In a virtual environment, the `python` or `python3` commands automatically use the virtual environment's version of Python and installed packages instead of the system Python.
-
-To leave a virtual environment, run the following command:
-
-[source,console?prompt=(<env-name>) $]
++
+When you finish working on a project, run the following command from any directory to leave the virtual environment:
++
+[source,console?prompt=(env) $]
 ----
-(<env-name>) $ deactivate
+(env) $ deactivate
 ----
 
-==== Use a separate environment for each project
-
-Many users create separate virtual environments for each Python project. Locate the virtual environment in the root folder of each project, typically with a shared name like `env`. Run the following command from the root folder of each project to create a virtual environment configuration folder:
-
+per-user environments::
++
+Instead of creating a virtual environment for each of your Python projects, you can create a single virtual environment for your user account. **Activate that virtual environment before running any of your Python code.** This approach can be more convenient for workflows that share many libraries across projects.
++
+When creating a virtual environment for multiple projects across an entire user account, consider locating the virtual environment configuration files in your home directory. Store your configuration in a https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments[folder whose name begins with a period] to hide the folder by default, preventing it from cluttering your home folder.
++
+Use the following command to create a virtual environment in a hidden folder in the current user's home directory:
++
 [source,console]
 ----
-$ python -m venv env
+$ python -m venv ~/.env
 ----
-
-Before you work on a project, run the following command from the root of the project to start using the virtual environment:
-
++
+Run the following command from any directory to start using the virtual environment:
++
 [source,console]
 ----
-$ source env/bin/activate
+$ source ~/.env/bin/activate
 ----
-
++
 You should then see a prompt similar to the following:
-
-[source,console?prompt=(env) $]
++
+[source,console?prompt=(.env) $]
 ----
-(env) $
+(.env) $
+----
++
+To leave the virtual environment, run the following command from any directory:
++
+[source,console?prompt=(.env) $]
+----
+(.env) $ deactivate
 ----
+======
 
-When you finish working on a project, run the following command from any directory to leave the virtual environment:
+===== Create a virtual environment
 
-[source,console?prompt=(env) $]
+Run the following command to create a virtual environment configuration folder, replacing `<env-name>` with the name you would like to use for the virtual environment (e.g. `env`):
+
+[source,console]
 ----
-(env) $ deactivate
+$ python -m venv <env-name>
 ----
 
-==== Use a separate environment for each user
-
-Instead of creating a virtual environment for each of your Python projects, you can create a single virtual environment for your user account. **Activate that virtual environment before running any of your Python code.** This approach can be more convenient for workflows that share many libraries across projects.
+TIP: Pass the `--system-site-packages` flag before the folder name to preload all of the currently installed packages in your system Python installation into the virtual environment.
 
-When creating a virtual environment for multiple projects across an entire user account, consider locating the virtual environment configuration files in your home directory. Store your configuration in a https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#Unix_and_Unix-like_environments[folder whose name begins with a period] to hide the folder by default, preventing it from cluttering your home folder.
+===== Enter a virtual environment
 
-Use the following command to create a virtual environment in a hidden folder in the current user's home directory:
+Then, execute the `bin/activate` script in the virtual environment configuration folder to enter the virtual environment:
 
 [source,console]
 ----
-$ python -m venv ~/.env
+$ source <env-name>/bin/activate
 ----
 
-Run the following command from any directory to start using the virtual environment:
+You should then see a prompt similar to the following:
 
-[source,console]
+[source,console?prompt=(<env-name>) $]
 ----
-$ source ~/.env/bin/activate
+(<env-name>) $
 ----
 
-You should then see a prompt similar to the following:
+The `(<env-name>)` command prompt prefix indicates that the current terminal session is in a virtual environment named `<env-name>`.
 
-[source,console?prompt=(.env) $]
+To check that you're in a virtual environment, use `pip list` to view the list of installed packages:
+
+[source,console?prompt=(<env-name>) $]
 ----
-(.env) $
+(<env-name>) $ pip list
+Package    Version
+---------- -------
+pip        23.0.1
+setuptools 66.1.1
 ----
 
-To leave the virtual environment, run the following command from any directory:
+The list should be much shorter than the list of packages installed in your system Python. You can now safely install packages with `pip`. Any packages you install with `pip` while in a virtual environment only install to that virtual environment. In a virtual environment, the `python` or `python3` commands automatically use the virtual environment's version of Python and installed packages instead of the system Python.
 
-[source,console?prompt=(.env) $]
+===== Exit a virtual environment
+
+To leave a virtual environment, run the following command:
+
+[source,console?prompt=(<env-name>) $]
 ----
-(.env) $ deactivate
+(<env-name>) $ deactivate
 ----
 
 === Use the Thonny editor

documentation/asciidoc/computers/remote-access/ssh.adoc

@@ -65,7 +65,7 @@ Enter your account password when prompted.
 
 You should now see the Raspberry Pi command prompt:
 
-[source,console]
+[source,console?prompt=<username>@<hostname> ~ $]
 ----
 <username>@<hostname> ~ $
 ----