Use tabs for virtualenv options

raspberrypi · Sep 18, 2024 · 96996d6 · 96996d6
1 parent d51377f
commit 96996d6
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 67 deletions.
diff --git a/documentation/asciidoc/computers/os/using-python.adoc b/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

diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/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> ~ $
 ----