docs: Add terminal.detect_venv; only detect venv with bin subdir (#17437)

Peter Tripp created 1 year ago

- Add docs for terminal.detect_venv
- Only detect venv with bin subdir

Change summary

crates/project/src/terminals.rs |  3 +
docs/src/configuring-zed.md     | 39 +++++++++++++++++++++++++++++++++++
docs/src/languages/python.md    |  5 ++++
3 files changed, 46 insertions(+), 1 deletion(-)

Detailed changes

crates/project/src/terminals.rs

@@ -264,7 +264,8 @@ impl Project {
             .into_iter()
             .map(|virtual_environment_name| abs_path.join(virtual_environment_name))
             .find(|venv_path| {
-                self.find_worktree(&venv_path, cx)
+                let bin_path = venv_path.join("bin");
+                self.find_worktree(&bin_path, cx)
                     .and_then(|(worktree, relative_path)| {
                         worktree.read(cx).entry_for_path(&relative_path)
                     })

docs/src/configuring-zed.md

@@ -1278,6 +1278,12 @@ List of `integer` column numbers
     "blinking": "terminal_controlled",
     "copy_on_select": false,
     "dock": "bottom",
+    "detect_venv": {
+      "on": {
+        "directories": [".env", "env", ".venv", "venv"],
+        "activate_script": "default"
+      }
+    }
     "env": {},
     "font_family": null,
     "font_features": null,
@@ -1570,6 +1576,39 @@ See Buffer Font Features
 }
 ```
 
+## Terminal: Detect Virtual Environments {#terminal-detect_venv}
+
+- Description: Activate the [Python Virtual Environment](https://docs.python.org/3/library/venv.html), if one is found, in the terminal's working directory (as resolved by the working_directory and automatically activating the virtual environemtn
+- Setting: `detect_venv`
+- Default:
+
+```json
+{
+  "terminal":
+    "detect_venv": {
+      "on": {
+        // Default directories to search for virtual environments, relative
+        // to the current working directory. We recommend overriding this
+        // in your project's settings, rather than globally.
+        "directories": [".venv", "venv"],
+        // Can also be `csh`, `fish`, and `nushell`
+        "activate_script": "default"
+      }
+    }
+  }
+}
+```
+
+Disable with:
+
+```json
+{
+  "terminal":
+    "detect_venv": "off"
+  }
+}
+```
+
 ## Terminal: Toolbar
 
 - Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.

docs/src/languages/python.md

@@ -100,6 +100,11 @@ The Pyright language server does not provide code formatting or linting. If you
 
 A common tool for formatting Python code is [Ruff](https://docs.astral.sh/ruff/). It is another tool written in Rust, an extremely fast Python linter and code formatter. It is available through the [Ruff extension](https://github.com/zed-industries/zed/tree/main/extensions/ruff/). To configure the Ruff extension to work within Zed, see the setup documentation [here](https://docs.astral.sh/ruff/editors/setup/#zed).
 
+## Virtual Environments in the Terminal {#terminal-detect_venv}
+
+Zed will also detect virtual environments and automatically activate them in terminal if available.
+See: [detect_venv documentation](https://zed.dev/docs/configuring-zed#terminal-detect_venv) for more.
+
 <!--
 TBD: Expand Python Ruff docs.
 TBD: Ruff pyproject.toml, ruff.toml docs. `ruff.configuration`.