From c353e2593569ff5d048b2ee7559d92e46c21877f Mon Sep 17 00:00:00 2001 From: cwebster-99 Date: Fri, 22 Aug 2025 12:29:35 -0500 Subject: [PATCH 1/3] Initial changes --- docs/python/environments.md | 77 ++++++++++++--- .../python-environments-activity-bar.png | 3 + docs/python/python-quick-start.md | 16 +++ docs/python/python-tutorial.md | 80 ++++++++++++--- docs/python/settings-reference.md | 11 ++- python-environments-screenshots.md | 97 +++++++++++++++++++ 6 files changed, 253 insertions(+), 31 deletions(-) create mode 100644 docs/python/images/environments/python-environments-activity-bar.png create mode 100644 python-environments-screenshots.md diff --git a/docs/python/environments.md b/docs/python/environments.md index 92864538ec..d64a231794 100644 --- a/docs/python/environments.md +++ b/docs/python/environments.md @@ -8,7 +8,31 @@ MetaSocialImage: images/tutorial/python-social.png An "environment" in Python is the context in which a Python program runs that consists of an interpreter and any number of installed packages. -> **Note**: If you'd like to become more familiar with the Python programming language, review [More Python resources](#more-python-resources). +> **Note**: If you'd like to become more familiar with the Python programming language, review [more Python resources](#more-python-resources). + +## Python Environments extension + +Python environments are managed via the Python Environments extension. The extension provides a dedicated view in the Activity Bar for creating, managing, and switching between environments, as well as installing and uninstalling packages. + +### Python Environments view + +The Python Environments view can be accessed from the Activity Bar and provides a unified interface for managing your Python projects and environments: + +![Python Environments view in VS Code (Screenshot placeholder)]() + +The view consists of two main sections: + +1. **Python Projects**: Shows all the projects in your workspace and their selected environments. From here you can: + - Add existing folders as Python projects + - Auto-find Python projects in your workspace + - Create new projects from templates + - Select different environments for each project + +2. **Environment Managers**: Shows all available environment managers with their environments. From here you can: + - Create new environments + - Delete environments + - Manage packages + - Activate environments in terminals ## Types of Python environments @@ -30,7 +54,7 @@ A [**virtual environment**](https://docs.python.org/3/glossary.html#term-virtual #### Conda environments -A **conda environment** is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)).Choosing between conda and virtual environments depends on your packaging needs, team standards, etc. +A **conda environment** is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)). Choosing between conda and virtual environments depends on your packaging needs, team standards, etc. ### Python environment tools @@ -44,27 +68,37 @@ The following table lists the various tools involved with Python environments: ## Creating environments -### Using the Create Environment command +### Quick Create -To create local environments in VS Code using virtual environments or Anaconda, you can follow these steps: open the Command Palette (`kb(workbench.action.showCommands)`), search for the **Python: Create Environment** command, and select it. +Quick create allows for a one-click environment creation flow, choosing the defaults for you. Quick create configures a virutal environment using the default environment manager and the latest Python version, and installing dependencies found in a `requirements.txt` or `pyproject.toml` file. -The command presents a list of environment types: **Venv** or **Conda**. +1. Open the Python Environments view from the Activity Bar +2. Under "Environment Managers", find your preferred environment manager (e.g., venv) +3. Select the **Create Environment** option +4. Choose **Quick Create** to automatically create a virtual environment using: + - Your default environment manager + - The latest Python version + - Workspace dependencies (if available) -![Create Environment dropdown](images/environments/create_environment_dropdown.png) +### Custom environment creation -If you are creating an environment using **Venv**, the command presents a list of interpreters that can be used as a base for the new virtual environment. +For more control over your environment settings, choose custom environment creation. -![Virtual environment interpreter selection](images/environments/interpreters-list.png) +1. Open the Python Environments view from the Activity Bar +2. Under "Environment Managers", find your preferred environment manager +3. Select **Create Environment** +4. Choose **Custom Create** +5. Follow the prompts to specify: + - Python version + - Environment name + - Packages to install + - Additional options specific to your environment manager -If you are creating an environment using **Conda**, the command presents a list of Python versions that can be used for your project. - -![Conda environment Python version selection](images/environments/conda_environment_python_versions.png) - -After selecting the desired interpreter or Python version, a notification will show the progress of the environment creation and the environment folder will appear in your workspace. +You can continue to create environments in VS Code using the Command Palette (Ctrl/Cmd + Shift + P) and searching for **Python: Create Environment**. ![Create environment status notification](images/environments/create_environment_prompt_status.png) -> **Note**: The command will also install necessary packages outlined in a requirements/dependencies file, such as `requirements.txt`, `pyproject.toml`, or `environment.yml`, located in the project folder. It will also add a `.gitignore` file to the virtual environment to help prevent you from accidentally committing the virtual environment to source control. +> **Note**: The Create Environment command will install packages outlined in a requirements/dependencies file, such as `requirements.txt`, `pyproject.toml`, or `environment.yml`, located in the project folder. It will also add a `.gitignore` file to the virtual environment to help prevent you from accidentally committing the virtual environment to source control. ### Create a virtual environment in the terminal @@ -116,7 +150,20 @@ Additional notes: ### Select and activate an environment -The Python extension tries to find and then select what it deems the best environment for the workspace. If you would prefer to select a specific environment, use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). +The Python extension attempts to find and select what it deems the best environment for the workspace. If you would prefer to select a specific environment, you can do so in one of the following ways: + +#### Using the Python Environments extension + +1. Open the Python Environments view from the Activity Bar +2. Under "Python Projects", find your project +3. Select the current environment to open a dropdown list of available environments +4. Choose the environment you want to use for the project + +Alternatively, under "Environment Managers", you can navigate to any environment and use the "Select" option to choose it for your workspace. + +#### Using the Select Interpreter command + +Use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). ![Python: Select Interpreter command](images/environments/select-interpreters-command.png) diff --git a/docs/python/images/environments/python-environments-activity-bar.png b/docs/python/images/environments/python-environments-activity-bar.png new file mode 100644 index 0000000000..a317a9cb48 --- /dev/null +++ b/docs/python/images/environments/python-environments-activity-bar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6c8231802c8f9294b28f7da5f055062303749edc5f943bd88e394e62d42c396f +size 37359 diff --git a/docs/python/python-quick-start.md b/docs/python/python-quick-start.md index 1c00a064c0..4c8f36c4a5 100644 --- a/docs/python/python-quick-start.md +++ b/docs/python/python-quick-start.md @@ -22,6 +22,22 @@ To further customize VS Code for Python, you can leverage the [Python profile te ## How to create and open a Python project or file +You can quickly create a scaffolded Python project for scripts or a Python package. + +1. Open the **Python Environments** view from the Activity Bar. + +![Screenshot showing the Python Environments Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) + +2. Under "Python Projects", select **Create New**. + +3. Choose from available project templates: + - **Package**: A structured Python package with `__init__.py` and setup configurations. + - **Script**: A simple project for standalone Python scripts. + +4. Follow the prompts to specify the project name, location, and environment settings. + +5. The extension will create the project structure and configure a virtual environment automatically. + If you have an existing Python project you wish to work on in VS Code, you can begin by opening your folder or file from the VS Code Welcome page or File Explorer view, or by selecting **File > Open Folder** (`kb(workbench.action.files.openFolder)`) or **File > Open File** (`kb(workbench.action.files.openFile)`). You can create a new Python file by selecting **New File** on the VS Code Welcome page and then selecting **Python file**, or by navigating to **File > New File** (`kb(workbench.action.files.newFile)`). diff --git a/docs/python/python-tutorial.md b/docs/python/python-tutorial.md index 079451090f..48b34ebc2e 100644 --- a/docs/python/python-tutorial.md +++ b/docs/python/python-tutorial.md @@ -81,25 +81,29 @@ Alternately, you can create a folder through the operating system UI, then use V ## Create a virtual environment -A best practice among Python developers is to use a project-specific `virtual environment`. Once you activate that environment, any packages you then install are isolated from other environments, including the global interpreter environment, reducing many complications that can arise from conflicting package versions. You can create non-global environments in VS Code using Venv or Anaconda with **Python: Create Environment**. +A best practice among Python developers is to use a project-specific `virtual environment`. Once you activate that environment, any packages you then install are isolated from other environments, including the global interpreter environment, reducing many complications that can arise from conflicting package versions. -Open the Command Palette (`kb(workbench.action.showCommands)`), start typing the **Python: Create Environment** command to search, and then select the command. +### Using the Python Environments extension -The command presents a list of environment types, Venv or Conda. For this example, select **Venv**. +The Python Environments extension provides a dedicated interface for managing environments. To create a virtual environment: -![Create Environment dropdown](images/environments/create_environment_dropdown.png) +1. Open the Python Environments view from the Activity Bar on the left side of VS Code. -The command then presents a list of interpreters that can be used for your project. Select the interpreter you installed at the beginning of the tutorial. +2. Under "Environment Managers", select your preferred environment manager (such as venv). -![Virtual environment interpreter selection](images/environments/interpreters-list.png) +3. Select **Create Environment** or use the **Quick Create** option which automatically creates a new virtual environment using your default environment manager and the latest Python version. -After selecting the interpreter, a notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. + [TODO: Add screenshot of Python Environments Quick Create option in VS Code] -![Create environment status notification](images/environments/create_environment_prompt_status.png) +4. Follow the prompts to specify the Python version and environment name. -Ensure your new environment is selected by using the **Python: Select Interpreter** command from the **Command Palette**. +4. After selecting the interpreter, a notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. -![Select an Interpreter](images/tutorial/interpreter-venv.png) + ![Create environment status notification](images/environments/create_environment_prompt_status.png) + +5. Once created, your new environment will be available in the list and automatically selected for your workspace. + + ![Select an Interpreter](images/tutorial/interpreter-venv.png) > **Note**: For additional information about virtual environments, or if you run into an error in the environment creation process, see [Environments](/docs/python/environments.md#creating-environments). @@ -233,13 +237,27 @@ print(np.random.randint(1,9)) Next, run the file in the debugger using the "Python: Current file" configuration as described in the last section. -You should see the message, **"ModuleNotFoundError: No module named 'numpy'"**. This message indicates that the required package isn't available in your interpreter. If you're using an Anaconda distribution or have previously installed the `numpy` package you may not see this message. +You should see the message, **"ModuleNotFoundError: No module named 'numpy'"**. This message indicates that the required package isn't available in your interpreter. If you're using an Anaconda distribution or have previously installed the `numpy` package you may not see this message. Before proceeding, stop the debugger. + +Installing Python packages can be done fully within the UI. + +1. Open the **Python Environments** view from the Activity Bar. + +2. Locate your active environment under either "Python Projects" or "Environment Managers". -To install the `numpy` package, stop the debugger and use the Command Palette to run **Terminal: Create New Terminal** (`kb(workbench.action.terminal.new)`). This command opens a command prompt for your selected interpreter. +3. Expand your environment and the **Packages** node to view packages currently available in your environment. Select the package icon on the environment. -To install the required packages in your virtual environment, enter the following commands as appropriate for your operating system: +4. Select **Search common PyPI packages** and search for and select `numpy`. -1. Install the packages + [TODO: Add screenshot of Python Environments package management interface] + +5. Once installed, the package will appear in your environment's package list. + +### Using the terminal to install packages + +Alternatively, you can install packages using the terminal: + +Install the required packages in your virtual environment, entering the following commands as appropriate for your operating system: ```bash # Don't use with Anaconda distributions because they include matplotlib already. @@ -255,7 +273,39 @@ To install the required packages in your virtual environment, enter the followin python3 -m pip install numpy ``` -1. Now, rerun the program, with or without the debugger, to view the output! +3. Now, rerun the program, with or without the debugger, to view the output! + +### Managing dependencies across environments + +When working on Python projects, it's essential to manage your dependencies effectively. One useful tip is to use the `pip freeze > requirements.txt` command. This command helps you create a `requirements.txt` file that lists all the packages installed in your virtual environment. This file can then be used to recreate the same environment elsewhere. + +Follow these steps to create a `requirements.txt` file: + +1. Activate your virtual environment, if you haven't already. + + ```bash + source venv/bin/activate # On macOS/Linux + ``` + + ```powershell + .\venv\Scripts\activate # On Windows + ``` + +2. Generate the `requirements.txt` file. + + ```powershell + pip freeze > requirements.txt + ``` + +You can now use the newly generated `requirements.txt` file to install dependencies in another environment. Furthermore, you can continue to add dependencies to it as your project may grow in complexity. + + ```powershell + pip install -r requirements.txt + ``` + +By following these steps, you ensure that your project dependencies are consistent across different environments, making it easier to collaborate with others and deploy your project. + +Congrats on completing the Python tutorial! During the course of this tutorial, you learned how to create a Python project, create a virtual environment, run and debug your Python code, and install Python packages. Explore additional resources to learn how to get the most out of Python in Visual Studio Code! ### Managing dependencies across environments When working on Python projects, it’s essential to manage your dependencies effectively. One useful tip is to use the `pip freeze > requirements.txt` command. This command helps you create a `requirements.txt` file that lists all the packages installed in your virtual environment. This file can then be used to recreate the same environment elsewhere. diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index 6928893c26..762a92ef54 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -1,5 +1,4 @@ --- -ContentId: d256dc5c-95e9-4c02-a82f-947bf34a3517 DateApproved: 3/6/2023 MetaDescription: Settings Reference for the Python extension in Visual Studio Code MetaSocialImage: images/tutorial/python-social.png @@ -30,6 +29,16 @@ For general information about working with settings in VS Code, refer to [User a | terminal.launchArgs | `[]` | Launch arguments that are given to the Python interpreter when you run a file using commands such as **Python: Run Python File in Terminal**.
In the `launchArgs` list, each item is a top-level command-line element that's separated by a space (quoted values that contain spaces are a single top-level element and are thus one item in the list).
For example, for the arguments `--a --b --c {"value1" : 1, "value2" : 2}`, the list items should be `["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]`.
Note that VS Code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in `launch.json`. | | venvFolders | `[]` | Paths to folders where virtual environments are created.
Depending on the virtualization tool used, it can be the project itself: `${workspaceFolder}`, or separate folders for all virtual environments located side by side: `.\envs`, `~/.virtualenvs`, and so on. | +## Python Environments extension settings + +| Setting
(python-envs.) | Default | Description | +| --- | --- | --- | +| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. | +| defaultPackageManager | `"ms-python.python:pip"` | The default package manager to use for installing and managing packages. This is often dictated by the default environment manager but can be customized. | +| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. Format: `[{"path": "/path/to/workspace", "envManager": "ms-python.python:venv", "packageManager": "ms-python.python:pip"}]`. | +| terminal.showActivateButton | `false` | (Experimental) Show a button in the terminal to activate/deactivate the current environment for the terminal. This button is only shown if the active terminal is associated with a project that has an activatable environment. | +| terminal.autoActivationType | `"command"` | Specifies how the extension can activate an environment in a terminal. Using Shell Startup requires changes to the shell script file and is only enabled for the following shells: zsh, fsh, pwsh, bash, cmd. When set to command, any shell can be activated. This setting applies only when terminals are created. | + ## Debugger Settings ### General debugging diff --git a/python-environments-screenshots.md b/python-environments-screenshots.md new file mode 100644 index 0000000000..27bd481fc8 --- /dev/null +++ b/python-environments-screenshots.md @@ -0,0 +1,97 @@ +# Screenshots Needed for Python Environments Extension Documentation + +This document lists all the screenshots needed for the updated Python documentation that references the new Python Environments extension. + +## python-tutorial.md + +1. **Python Environments extension in Activity Bar** + - Description: Show the Python Environments icon in the Activity Bar + - Location: First mention of the Python Environments extension + +2. **Create Environment UI** + - Description: Screenshot of the Create Environment dialog showing options for venv and conda + - Location: "Creating virtual environments" section + +3. **Python Environments View - Environment List** + - Description: Show the Environments panel with a list of available environments + - Location: "Creating virtual environments" section + +4. **Package Management UI** + - Description: Screenshot of the Packages view showing installed packages and search/install functionality + - Location: "Installing packages" section + +5. **Install Package Dialog** + - Description: Dialog for installing a new package with version specification + - Location: "Installing packages" section + +## python-quick-start.md + +1. **Python Environments in Activity Bar** + - Description: Python Environments icon in Activity Bar with panel open + - Location: "Python Environments in the Activity Bar" section + +2. **Create Project Dialog** + - Description: Screenshot of the Create Project dialog showing available templates + - Location: "Create a new Python project" section + +3. **Project Structure After Creation** + - Description: Explorer view showing the structure of a newly created project (from template) + - Location: "Create a new Python project" section + +## environments.md + +1. **Python Environments Extension Overview** + - Description: Full screenshot of the Python Environments extension UI with panels expanded + - Location: Introduction section + +2. **Environment List with Different Environment Types** + - Description: Show environments list with different types (venv, conda, system) + - Location: "The Python Environments extension" section + +3. **Environment Creation Options** + - Description: Create Environment dialog showing all options (venv, conda) + - Location: "Creating environments" section + +4. **Environment Details Panel** + - Description: Environment details showing version, path, packages, etc. + - Location: "Managing environments" section + +5. **Package Management Interface** + - Description: Packages view showing search, install, update functionality + - Location: "Managing packages" section + +6. **Create Project Templates** + - Description: Create Project dialog showing all available templates + - Location: "Creating and managing projects" section + +7. **Terminal with Environment Activation** + - Description: Terminal showing an activated environment with appropriate prompt + - Location: "Terminal integration" section + +## settings-reference.md + +1. **Python Environments Extension Settings** + - Description: Settings UI showing Python Environments extension settings + - Location: "Python Environments extension settings" section + +## Additional Contextual Screenshots + +1. **Python Extension Recommendations** + - Description: Show VS Code recommending the Python Environments extension + - Location: Could be added to introduction of environments.md + +2. **Environment Selection in Status Bar** + - Description: Status bar showing selected Python environment + - Location: Could be referenced in several documents + +3. **Python Environments Panel in Explorer View** + - Description: Alternative view showing Python Environments panel docked with Explorer + - Location: For flexibility in UI arrangement references + +## Notes for Screenshot Creation + +- Use consistent VS Code theme for all screenshots (preferably the default dark or light theme) +- Consider showing both Windows and non-Windows examples where platform differences exist +- Ensure readable text size and focus on relevant UI elements +- For dialog screenshots, capture the entire dialog box with all options visible +- For terminal screenshots, ensure the command prompt and output are clearly visible \ No newline at end of file From 426bdaa9cc3a6099461afe147f6039c2caaad0b4 Mon Sep 17 00:00:00 2001 From: cwebster-99 Date: Mon, 25 Aug 2025 13:28:36 -0500 Subject: [PATCH 2/3] Updating screenshots --- docs/python/environments.md | 6 +- .../environment-creation-dropdown.png | 3 + .../selected-interpreter-envs.png | 3 + .../images/quick-start/create-project.png | 3 + .../images/quick-start/updated-ui-tour.png | 3 + docs/python/images/tutorial/install-numpy.png | 3 + .../images/tutorial/manage-packages.png | 3 + .../images/tutorial/numpy-installed.png | 3 + docs/python/python-quick-start.md | 6 +- docs/python/python-tutorial.md | 20 +++--- python-environments-screenshots.md | 67 ------------------- 11 files changed, 41 insertions(+), 79 deletions(-) create mode 100644 docs/python/images/environments/environment-creation-dropdown.png create mode 100644 docs/python/images/environments/selected-interpreter-envs.png create mode 100644 docs/python/images/quick-start/create-project.png create mode 100644 docs/python/images/quick-start/updated-ui-tour.png create mode 100644 docs/python/images/tutorial/install-numpy.png create mode 100644 docs/python/images/tutorial/manage-packages.png create mode 100644 docs/python/images/tutorial/numpy-installed.png diff --git a/docs/python/environments.md b/docs/python/environments.md index d64a231794..3fc830d060 100644 --- a/docs/python/environments.md +++ b/docs/python/environments.md @@ -18,7 +18,7 @@ Python environments are managed via the Python Environments extension. The exten The Python Environments view can be accessed from the Activity Bar and provides a unified interface for managing your Python projects and environments: -![Python Environments view in VS Code (Screenshot placeholder)]() +![Python Environments view in the Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) The view consists of two main sections: @@ -70,7 +70,7 @@ The following table lists the various tools involved with Python environments: ### Quick Create -Quick create allows for a one-click environment creation flow, choosing the defaults for you. Quick create configures a virutal environment using the default environment manager and the latest Python version, and installing dependencies found in a `requirements.txt` or `pyproject.toml` file. +Quick create allows for a one-click environment creation flow, choosing the defaults for you. Quick create configures a virtual environment using the default environment manager and the latest Python version, and installing dependencies found in a `requirements.txt` or `pyproject.toml` file. 1. Open the Python Environments view from the Activity Bar 2. Under "Environment Managers", find your preferred environment manager (e.g., venv) @@ -80,6 +80,8 @@ Quick create allows for a one-click environment creation flow, choosing the defa - The latest Python version - Workspace dependencies (if available) +![Screenshot of the environment creation options for venv.](/docs/python/images/environments/environment-creation-dropdown.png) + ### Custom environment creation For more control over your environment settings, choose custom environment creation. diff --git a/docs/python/images/environments/environment-creation-dropdown.png b/docs/python/images/environments/environment-creation-dropdown.png new file mode 100644 index 0000000000..8385230184 --- /dev/null +++ b/docs/python/images/environments/environment-creation-dropdown.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc3065655dc8ad030ea257ca219df104f3fc26b7c40210c251bd3003bd3a9b82 +size 28521 diff --git a/docs/python/images/environments/selected-interpreter-envs.png b/docs/python/images/environments/selected-interpreter-envs.png new file mode 100644 index 0000000000..f46273242f --- /dev/null +++ b/docs/python/images/environments/selected-interpreter-envs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9283121a9d91fed23f5de1079f153475bade1c6313768d3741722b3403efc8a8 +size 40392 diff --git a/docs/python/images/quick-start/create-project.png b/docs/python/images/quick-start/create-project.png new file mode 100644 index 0000000000..d9a1622a92 --- /dev/null +++ b/docs/python/images/quick-start/create-project.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4d3e416610c4423d0f69bc2d472ff93a5cc946fcafa1658180e35f28e9ebf301 +size 9888 diff --git a/docs/python/images/quick-start/updated-ui-tour.png b/docs/python/images/quick-start/updated-ui-tour.png new file mode 100644 index 0000000000..61dd607513 --- /dev/null +++ b/docs/python/images/quick-start/updated-ui-tour.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d7659e9484aa1b7c11b38d86a91712ef50cd9200f10a4666de0d47cdf722ab0f +size 194202 diff --git a/docs/python/images/tutorial/install-numpy.png b/docs/python/images/tutorial/install-numpy.png new file mode 100644 index 0000000000..f1e06d07c1 --- /dev/null +++ b/docs/python/images/tutorial/install-numpy.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c219d88fac45f3693e4fbb0d8322e100f5c84003941460387c96d2488bca70ed +size 30515 diff --git a/docs/python/images/tutorial/manage-packages.png b/docs/python/images/tutorial/manage-packages.png new file mode 100644 index 0000000000..5ce49ab947 --- /dev/null +++ b/docs/python/images/tutorial/manage-packages.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:46567a67e503dec6f258199af4fc5fc6891b4494db068e34c3c4a6d0dd49ec66 +size 17649 diff --git a/docs/python/images/tutorial/numpy-installed.png b/docs/python/images/tutorial/numpy-installed.png new file mode 100644 index 0000000000..73da1d18e4 --- /dev/null +++ b/docs/python/images/tutorial/numpy-installed.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b28f676781275bd1d0e5c58e47a44b7837720205b7923d3ba55db434de9633a5 +size 22308 diff --git a/docs/python/python-quick-start.md b/docs/python/python-quick-start.md index 4c8f36c4a5..344c2a3892 100644 --- a/docs/python/python-quick-start.md +++ b/docs/python/python-quick-start.md @@ -28,7 +28,9 @@ You can quickly create a scaffolded Python project for scripts or a Python packa ![Screenshot showing the Python Environments Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) -2. Under "Python Projects", select **Create New**. +2. In the "Python Projects" section, select **Add Python Project** and **Create New**. + +![Screenshot showing the UI entry point to add a new python project.](/docs/python/images/quick-start/create-project.png) 3. Choose from available project templates: - **Package**: A structured Python package with `__init__.py` and setup configurations. @@ -48,7 +50,7 @@ You can create a new Python file by selecting **New File** on the VS Code Welcom When you launch VS Code for the very first time, you will need to install the Python extension to get Python-specific features and UI. Let’s look at the UI after installing the Python extension: -![Image of the Python UI highlights in VS Code.](images/quick-start/ui-tour.png) +![Image of the Python UI highlights in VS Code.](images/quick-start/updated-ui-tour.png) ## Code Actions diff --git a/docs/python/python-tutorial.md b/docs/python/python-tutorial.md index 48b34ebc2e..c8ce6fd421 100644 --- a/docs/python/python-tutorial.md +++ b/docs/python/python-tutorial.md @@ -89,21 +89,21 @@ The Python Environments extension provides a dedicated interface for managing en 1. Open the Python Environments view from the Activity Bar on the left side of VS Code. -2. Under "Environment Managers", select your preferred environment manager (such as venv). +![Screenshot of the Python Environments panel from the Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) -3. Select **Create Environment** or use the **Quick Create** option which automatically creates a new virtual environment using your default environment manager and the latest Python version. +2. Under "Environment Managers", select the `+` next to your preferred environment manager (such as Venv). - [TODO: Add screenshot of Python Environments Quick Create option in VS Code] +3. Select the **Quick Create** option which automatically creates a new virtual environment using your default environment manager and the latest Python version. -4. Follow the prompts to specify the Python version and environment name. + ![Screenshot of the environment creation options for venv.](/docs/python/images/environments/environment-creation-dropdown.png) -4. After selecting the interpreter, a notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. +4. A notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. ![Create environment status notification](images/environments/create_environment_prompt_status.png) 5. Once created, your new environment will be available in the list and automatically selected for your workspace. - ![Select an Interpreter](images/tutorial/interpreter-venv.png) + ![Select an Interpreter](/docs/python/images/environments/selected-interpreter-envs.png) > **Note**: For additional information about virtual environments, or if you run into an error in the environment creation process, see [Environments](/docs/python/environments.md#creating-environments). @@ -243,16 +243,20 @@ Installing Python packages can be done fully within the UI. 1. Open the **Python Environments** view from the Activity Bar. -2. Locate your active environment under either "Python Projects" or "Environment Managers". +2. Locate your active environment under "Environment Managers". 3. Expand your environment and the **Packages** node to view packages currently available in your environment. Select the package icon on the environment. +![Screenshot of UI entry point for package management.](/docs/python/images/tutorial/manage-packages.png) + 4. Select **Search common PyPI packages** and search for and select `numpy`. - [TODO: Add screenshot of Python Environments package management interface] +![Screenshot of package installation UI.](/docs/python/images/tutorial/install-numpy.png) 5. Once installed, the package will appear in your environment's package list. +![Screenshot showing numpy installed in the virtual environment.](/docs/python/images/tutorial/numpy-installed.png) + ### Using the terminal to install packages Alternatively, you can install packages using the terminal: diff --git a/python-environments-screenshots.md b/python-environments-screenshots.md index 27bd481fc8..cebab9e999 100644 --- a/python-environments-screenshots.md +++ b/python-environments-screenshots.md @@ -1,42 +1,3 @@ -# Screenshots Needed for Python Environments Extension Documentation - -This document lists all the screenshots needed for the updated Python documentation that references the new Python Environments extension. - -## python-tutorial.md - -1. **Python Environments extension in Activity Bar** - - Description: Show the Python Environments icon in the Activity Bar - - Location: First mention of the Python Environments extension - -2. **Create Environment UI** - - Description: Screenshot of the Create Environment dialog showing options for venv and conda - - Location: "Creating virtual environments" section - -3. **Python Environments View - Environment List** - - Description: Show the Environments panel with a list of available environments - - Location: "Creating virtual environments" section - -4. **Package Management UI** - - Description: Screenshot of the Packages view showing installed packages and search/install functionality - - Location: "Installing packages" section - -5. **Install Package Dialog** - - Description: Dialog for installing a new package with version specification - - Location: "Installing packages" section - -## python-quick-start.md - -1. **Python Environments in Activity Bar** - - Description: Python Environments icon in Activity Bar with panel open - - Location: "Python Environments in the Activity Bar" section - -2. **Create Project Dialog** - - Description: Screenshot of the Create Project dialog showing available templates - - Location: "Create a new Python project" section - -3. **Project Structure After Creation** - - Description: Explorer view showing the structure of a newly created project (from template) - - Location: "Create a new Python project" section ## environments.md @@ -67,31 +28,3 @@ This document lists all the screenshots needed for the updated Python documentat 7. **Terminal with Environment Activation** - Description: Terminal showing an activated environment with appropriate prompt - Location: "Terminal integration" section - -## settings-reference.md - -1. **Python Environments Extension Settings** - - Description: Settings UI showing Python Environments extension settings - - Location: "Python Environments extension settings" section - -## Additional Contextual Screenshots - -1. **Python Extension Recommendations** - - Description: Show VS Code recommending the Python Environments extension - - Location: Could be added to introduction of environments.md - -2. **Environment Selection in Status Bar** - - Description: Status bar showing selected Python environment - - Location: Could be referenced in several documents - -3. **Python Environments Panel in Explorer View** - - Description: Alternative view showing Python Environments panel docked with Explorer - - Location: For flexibility in UI arrangement references - -## Notes for Screenshot Creation - -- Use consistent VS Code theme for all screenshots (preferably the default dark or light theme) -- Consider showing both Windows and non-Windows examples where platform differences exist -- Ensure readable text size and focus on relevant UI elements -- For dialog screenshots, capture the entire dialog box with all options visible -- For terminal screenshots, ensure the command prompt and output are clearly visible \ No newline at end of file From 98e61b65b29098f194a62277dc0d20bb3a905d1c Mon Sep 17 00:00:00 2001 From: cwebster-99 Date: Mon, 25 Aug 2025 16:44:39 -0500 Subject: [PATCH 3/3] remove planning doc --- python-environments-screenshots.md | 30 ------------------------------ 1 file changed, 30 deletions(-) delete mode 100644 python-environments-screenshots.md diff --git a/python-environments-screenshots.md b/python-environments-screenshots.md deleted file mode 100644 index cebab9e999..0000000000 --- a/python-environments-screenshots.md +++ /dev/null @@ -1,30 +0,0 @@ - -## environments.md - -1. **Python Environments Extension Overview** - - Description: Full screenshot of the Python Environments extension UI with panels expanded - - Location: Introduction section - -2. **Environment List with Different Environment Types** - - Description: Show environments list with different types (venv, conda, system) - - Location: "The Python Environments extension" section - -3. **Environment Creation Options** - - Description: Create Environment dialog showing all options (venv, conda) - - Location: "Creating environments" section - -4. **Environment Details Panel** - - Description: Environment details showing version, path, packages, etc. - - Location: "Managing environments" section - -5. **Package Management Interface** - - Description: Packages view showing search, install, update functionality - - Location: "Managing packages" section - -6. **Create Project Templates** - - Description: Create Project dialog showing all available templates - - Location: "Creating and managing projects" section - -7. **Terminal with Environment Activation** - - Description: Terminal showing an activated environment with appropriate prompt - - Location: "Terminal integration" section