new page about Python interpreters (#99)

* new page about Python interpreters

* feedback

* missed a couple things

Author: austin3dickey

_quarto.yml

@@ -63,6 +63,7 @@ website:
           contents:
             - managing-interpreters.qmd
             - interpreter-startup.qmd
+            - python-installations.qmd
             - r-installations.qmd
         - keyboard-shortcuts.qmd
         - data-explorer.qmd
@@ -84,7 +85,7 @@ website:
         - feedback.qmd
         - faqs.qmd
         - privacy.qmd
-        
+
 format:
   html:
     css: styles.css

interpreter-startup.qmd

@@ -8,7 +8,7 @@ When Positron starts for the first time in a new workspace, it will start a Pyth
 
 Typically when starting Python or R without other clues about which version to start, Positron will start the most recent version of the interpreter (e.g. if you have R 4.2 and R 4.3 installed, it'll start R 4.3).
 
-If you are an R user, see the [R discovery](r-installations.qmd) guide for more information on available installations.
+See the [Python discovery](python-installations.qmd) and [R discovery](r-installations.qmd) guides for more information on language-specific installations.
 
 ### RStudio detection
 

python-installations.qmd

@@ -0,0 +1,120 @@
+---
+title: "Discovering Python Installations"
+---
+
+This guide explains how Python installations are discovered and managed in Positron.
+
+## Python installation discovery
+
+Positron uses multiple strategies to discover Python interpreters and virtual environments across your system.
+The discovery process includes both global Python installations and various virtual environment managers.
+
+### Supported environment managers
+
+Positron supports the following Python environment managers:
+
+* **venv**: Standard library virtual environments created with `python -m venv`
+* **uv**: Virtual environments and Python installations managed by `uv`
+* **pyenv**: Python installations managed by `pyenv`, including virtual environments
+* **conda**: Conda environments created with `conda create` or `mamba create`
+
+Other tools may also be compatible, although they are not officially supported at this time.
+
+### Discovery locations
+
+Positron searches for Python interpreters in the following locations:
+
+**Virtual environments**
+
+* `.venv/` and `.conda/` folders in your [workspace](https://code.visualstudio.com/docs/editing/workspaces/workspaces#_singlefolder-workspaces) directory
+* Tool-managed project-specific installations in locations like `~/.local/share/virtualenvs` or where `conda` stores envs
+
+**Global Python installations**
+
+* System Python installations in standard locations like the user's `PATH`
+* `/opt/python`
+* Tool-managed installation locations like `~/.pyenv` or ` ~/.local/share/uv/python/`
+
+Note that using a system Python installation in a new session can lead to problems (see the official [guidance](https://packaging.python.org/en/latest/specifications/externally-managed-environments/) about this).
+For that reason, we recommend using virtual environments.
+
+**Custom locations**
+
+* Interpreters listed in the [`python.interpreters.[include,exclude,override]` settings](positron://settings/python.interpreters.include) (see [Related Settings](#related-settings) below for details)
+
+## Environment creation and discovery
+
+### Creating new environments
+
+You can create new Python environments directly from Positron using the _Python: Create Environment_ command:
+
+1. Open the Command Palette (<kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>)
+2. Select _Python: Create Environment_
+3. Choose from available environment providers:
+   - **uv**: Creates a uv-managed virtual environment (if uv is available)
+   - **venv**: Creates a standard virtual environment using `python -m venv`
+   - **conda**: Creates a conda environment (if conda is available)
+
+The environment will be created in your workspace and automatically discovered.
+
+You can also use the **New Folder From Template** feature to create a new Python project, and set up an environment as part of the project.
+
+### Discovering existing environments
+
+Positron automatically discovers environments when:
+
+- You open Positron
+- You open a new workspace folder
+- Certain file system changes are detected in watched directories
+- You manually refresh using the _Interpreter: Discover All Interpreters_ command
+
+The discovery process runs in the background and updates the interpreter list as new environments are found.
+
+## Discovery process details
+
+### Unsupported Python versions
+
+Positron only supports Python minor versions 3.9 through 3.13, which are the [currently supported versions](https://devguide.python.org/versions/).
+Other versions may be discovered, but you may run into issues using them.
+
+### Locator type
+
+Positron can use two different discovery mechanisms:
+
+* **JavaScript locator** (default): Pure TypeScript implementation for more comprehensive discovery
+* **Native locator** (experimental): Uses a native binary for faster discovery
+
+You can control this with the [`python.locator` setting](positron://settings/python.locator) (`"js"` or `"native"`).
+Keep in mind that the `native` locator is experimental and may not work completely as intended.
+
+## Troubleshooting
+
+### Environment not appearing
+
+If the above settings are configured correctly, and the Python version is supported, and _Interpreter: Discover All Interpreters_ or a restart of Positron is not helping, you can check logs. See more in the [troubleshooting guide](troubleshooting.qmd).
+
+For the `js` (default) locator, the discovery process is logged in the Python Language Pack channel of the Output panel.
+
+For the `native` locator, it is instead logged in the Python Locator channel.
+
+## Related settings
+
+Key settings that control Python environment discovery:
+
+### Discovery location settings
+* [`python.interpreters.include`](positron://settings/python.interpreters.include): Specific interpreter paths to include
+* [`python.interpreters.exclude`](positron://settings/python.interpreters.exclude): Interpreter paths to exclude from discovery
+* [`python.interpreters.override`](positron://settings/python.interpreters.override): Override the above two settings so only these are shown
+
+### Environment providers
+* [`python.environmentProviders.enable`](positron://settings/python.environmentProviders.enable): Enable/disable specific environment providers for environment creation (`Venv`, `Conda`, `uv`)
+
+### Discovery behavior
+* [`python.locator`](positron://settings/python.locator): Choose between "native" or "js" discovery methods
+* [`python.defaultInterpreterPath`](positron://settings/python.defaultInterpreterPath): Default Python interpreter path (used only the first time when no other interpreter takes precedence)
+
+## Related commands
+
+* _Interpreter: Discover All Interpreters_: Find new interpreters
+* _Interpreter: Select Interpreter Session_: Select an interpreter for a session
+* _Python: Create Environment_: Create a new virtual environment

r-installations.qmd

@@ -2,7 +2,7 @@
 title: "Discovering R Installations"
 ---
 
-This guide pertains to how R installations are discoverd and show up in the Interpreter picker.
+This guide pertains to how R installations are discovered and show up in the Interpreter picker.
 
 ## R installation discovery