[ty] Improve Python environment path documentation

crates/ty/src/args.rs

@@ -71,10 +71,16 @@ pub(crate) struct CheckCommand {
     ///
     /// ty uses your Python environment to resolve third-party imports in your code.
     ///
+    /// This can be a path to:
+    ///
+    /// - A Python interpreter, e.g. `.venv/bin/python3`
+    /// - A virtual environment directory, e.g. `.venv`
+    /// - A system Python [`sys.prefix`] directory, e.g. `/usr`
+    ///
     /// If you're using a project management tool such as uv or you have an activated Conda or virtual
     /// environment, you should not generally need to specify this option.
     ///
-    /// This option can be used to point to virtual or system Python environments.
+    /// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix
     #[arg(long, value_name = "PATH", alias = "venv")]
     pub(crate) python: Option<SystemPathBuf>,
 

crates/ty_project/src/metadata/options.rs

@@ -683,17 +683,20 @@ pub struct EnvironmentOptions {
     /// ty uses the `site-packages` directory of your project's Python environment
     /// to resolve third-party (and, in some cases, first-party) imports in your code.
     ///
+    /// This can be a path to:
+    ///
+    /// - A Python interpreter, e.g. `.venv/bin/python3`
+    /// - A virtual environment directory, e.g. `.venv`
+    /// - A system Python [`sys.prefix`] directory, e.g. `/usr`
+    ///
     /// If you're using a project management tool such as uv, you should not generally need to
     /// specify this option, as commands such as `uv run` will set the `VIRTUAL_ENV` environment
     /// variable to point to your project's virtual environment. ty can also infer the location of
     /// your environment from an activated Conda environment, and will look for a `.venv` directory
     /// in the project root if none of the above apply. Failing that, ty will look for a `python3`
     /// or `python` binary available in `PATH`.
     ///
-    /// Passing a path to a Python executable is supported, but passing a path to a dynamic executable
-    /// (such as a shim) is not currently supported.
-    ///
-    /// This option can be used to point to virtual or system Python environments.
+    /// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix
     #[serde(skip_serializing_if = "Option::is_none")]
     #[option(
         default = r#"null"#,