[ty] Improve documentation for extra-paths and python config settings (#20717)

Co-authored-by: Micha Reiser <micha@reiser.io>

crates/ty/docs/cli.md

@@ -54,7 +54,8 @@ over all configuration files.</p>
 </dd><dt id="ty-check--exclude"><a href="#ty-check--exclude"><code>--exclude</code></a> <i>exclude</i></dt><dd><p>Glob patterns for files to exclude from type checking.</p>
 <p>Uses gitignore-style syntax to exclude files and directories from type checking. Supports patterns like <code>tests/</code>, <code>*.tmp</code>, <code>**/__pycache__/**</code>.</p>
 </dd><dt id="ty-check--exit-zero"><a href="#ty-check--exit-zero"><code>--exit-zero</code></a></dt><dd><p>Always use exit code 0, even when there are error-level diagnostics</p>
-</dd><dt id="ty-check--extra-search-path"><a href="#ty-check--extra-search-path"><code>--extra-search-path</code></a> <i>path</i></dt><dd><p>Additional path to use as a module-resolution source (can be passed multiple times)</p>
+</dd><dt id="ty-check--extra-search-path"><a href="#ty-check--extra-search-path"><code>--extra-search-path</code></a> <i>path</i></dt><dd><p>Additional path to use as a module-resolution source (can be passed multiple times).</p>
+<p>This is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use <code>--python</code> to point ty to your Python environment if it is in an unusual location.</p>
 </dd><dt id="ty-check--help"><a href="#ty-check--help"><code>--help</code></a>, <code>-h</code></dt><dd><p>Print help (see a summary with '-h')</p>
 </dd><dt id="ty-check--ignore"><a href="#ty-check--ignore"><code>--ignore</code></a> <i>rule</i></dt><dd><p>Disables the rule. Can be specified multiple times.</p>
 </dd><dt id="ty-check--output-format"><a href="#ty-check--output-format"><code>--output-format</code></a> <i>output-format</i></dt><dd><p>The format to use for printing diagnostic messages</p>
@@ -67,11 +68,10 @@ over all configuration files.</p>
 </ul></dd><dt id="ty-check--project"><a href="#ty-check--project"><code>--project</code></a> <i>project</i></dt><dd><p>Run the command within the given project directory.</p>
 <p>All <code>pyproject.toml</code> files will be discovered by walking up the directory tree from the given project directory, as will the project's virtual environment (<code>.venv</code>) unless the <code>venv-path</code> option is set.</p>
 <p>Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.</p>
-</dd><dt id="ty-check--python"><a href="#ty-check--python"><code>--python</code></a>, <code>--venv</code> <i>path</i></dt><dd><p>Path to the Python environment.</p>
-<p>ty uses the Python environment to resolve type information and third-party dependencies.</p>
-<p>If not specified, ty will attempt to infer it from the <code>VIRTUAL_ENV</code> or <code>CONDA_PREFIX</code> environment variables, or discover a <code>.venv</code> directory in the project root or working directory.</p>
-<p>If a path to a Python interpreter is provided, e.g., <code>.venv/bin/python3</code>, ty will attempt to find an environment two directories up from the interpreter's path, e.g., <code>.venv</code>. At this time, ty does not invoke the interpreter to determine the location of the environment. This means that ty will not resolve dynamic executables such as a shim.</p>
-<p>ty will search in the resolved environment's <code>site-packages</code> directories for type information and third-party imports.</p>
+</dd><dt id="ty-check--python"><a href="#ty-check--python"><code>--python</code></a>, <code>--venv</code> <i>path</i></dt><dd><p>Path to your project's Python environment or interpreter.</p>
+<p>ty uses your Python environment to resolve third-party imports in your code.</p>
+<p>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.</p>
+<p>This option can be used to point to virtual or system Python environments.</p>
 </dd><dt id="ty-check--python-platform"><a href="#ty-check--python-platform"><code>--python-platform</code></a>, <code>--platform</code> <i>platform</i></dt><dd><p>Target platform to assume when resolving types.</p>
 <p>This is used to specialize the type of <code>sys.platform</code> and will affect the visibility of platform-specific functions and attributes. If the value is set to <code>all</code>, no assumptions are made about the target platform. If unspecified, the current system's platform will be used.</p>
 </dd><dt id="ty-check--python-version"><a href="#ty-check--python-version"><code>--python-version</code></a>, <code>--target-version</code> <i>version</i></dt><dd><p>Python version to assume when resolving types.</p>

crates/ty/docs/configuration.md

@@ -32,9 +32,14 @@ division-by-zero = "ignore"
 
 ### `extra-paths`
 
-List of user-provided paths that should take first priority in the module resolution.
-Examples in other type checkers are mypy's `MYPYPATH` environment variable,
-or pyright's `stubPath` configuration setting.
+User-provided paths that should take first priority in module resolution.
+
+This is an advanced option that should usually only be used for first-party or third-party
+modules that are not installed into your Python environment in a conventional way.
+Use the `python` option to specify the location of your Python environment.
+
+This option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath`
+configuration setting.
 
 **Default value**: `[]`
 
@@ -51,12 +56,21 @@ extra-paths = ["./shared/my-search-path"]
 
 ### `python`
 
-Path to the Python installation from which ty resolves type information and third-party dependencies.
+Path to your project's Python environment or interpreter.
 
-ty will search in the path's `site-packages` directories for type information and
-third-party imports.
+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 option is commonly used to specify the path to a virtual environment.
+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.
+
+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.
 
 **Default value**: `null`
 
@@ -66,7 +80,7 @@ This option is commonly used to specify the path to a virtual environment.
 
 ```toml
 [tool.ty.environment]
-python = "./.venv"
+python = "./custom-venv-location/.venv"
 ```
 
 ---

crates/ty/src/args.rs

@@ -51,21 +51,14 @@ pub(crate) struct CheckCommand {
     #[arg(long, value_name = "PROJECT")]
     pub(crate) project: Option<SystemPathBuf>,
 
-    /// Path to the Python environment.
+    /// Path to your project's Python environment or interpreter.
     ///
-    /// ty uses the Python environment to resolve type information and third-party dependencies.
+    /// ty uses your Python environment to resolve third-party imports in your code.
     ///
-    /// If not specified, ty will attempt to infer it from the `VIRTUAL_ENV` or `CONDA_PREFIX`
-    /// environment variables, or discover a `.venv` directory in the project root or working
-    /// directory.
+    /// 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.
     ///
-    /// If a path to a Python interpreter is provided, e.g., `.venv/bin/python3`, ty will attempt to
-    /// find an environment two directories up from the interpreter's path, e.g., `.venv`. At this
-    /// time, ty does not invoke the interpreter to determine the location of the environment. This
-    /// means that ty will not resolve dynamic executables such as a shim.
-    ///
-    /// ty will search in the resolved environment's `site-packages` directories for type
-    /// information and third-party imports.
+    /// This option can be used to point to virtual or system Python environments.
     #[arg(long, value_name = "PATH", alias = "venv")]
     pub(crate) python: Option<SystemPathBuf>,
 
@@ -74,6 +67,10 @@ pub(crate) struct CheckCommand {
     pub(crate) typeshed: Option<SystemPathBuf>,
 
     /// Additional path to use as a module-resolution source (can be passed multiple times).
+    ///
+    /// This is an advanced option that should usually only be used for first-party or third-party
+    /// modules that are not installed into your Python environment in a conventional way.
+    /// Use `--python` to point ty to your Python environment if it is in an unusual location.
     #[arg(long, value_name = "PATH")]
     pub(crate) extra_search_path: Option<Vec<SystemPathBuf>>,
 

crates/ty_project/src/metadata/options.rs

@@ -550,9 +550,14 @@ pub struct EnvironmentOptions {
     )]
     pub python_platform: Option<RangedValue<PythonPlatform>>,
 
-    /// List of user-provided paths that should take first priority in the module resolution.
-    /// Examples in other type checkers are mypy's `MYPYPATH` environment variable,
-    /// or pyright's `stubPath` configuration setting.
+    /// User-provided paths that should take first priority in module resolution.
+    ///
+    /// This is an advanced option that should usually only be used for first-party or third-party
+    /// modules that are not installed into your Python environment in a conventional way.
+    /// Use the `python` option to specify the location of your Python environment.
+    ///
+    /// This option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath`
+    /// configuration setting.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[option(
         default = r#"[]"#,
@@ -576,18 +581,27 @@ pub struct EnvironmentOptions {
     )]
     pub typeshed: Option<RelativePathBuf>,
 
-    /// Path to the Python installation from which ty resolves type information and third-party dependencies.
+    /// Path to your project's Python environment or interpreter.
     ///
-    /// ty will search in the path's `site-packages` directories for type information and
-    /// third-party imports.
+    /// 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 option is commonly used to specify the path to a virtual environment.
+    /// 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.
+    ///
+    /// 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.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[option(
         default = r#"null"#,
         value_type = "str",
         example = r#"
-            python = "./.venv"
+            python = "./custom-venv-location/.venv"
         "#
     )]
     pub python: Option<RelativePathBuf>,

ty.schema.json

@@ -62,7 +62,7 @@
       "type": "object",
       "properties": {
         "extra-paths": {
-          "description": "List of user-provided paths that should take first priority in the module resolution. Examples in other type checkers are mypy's `MYPYPATH` environment variable, or pyright's `stubPath` configuration setting.",
+          "description": "User-provided paths that should take first priority in module resolution.\n\nThis is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use the `python` option to specify the location of your Python environment.\n\nThis option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath` configuration setting.",
           "type": [
             "array",
             "null"
@@ -72,7 +72,7 @@
           }
         },
         "python": {
-          "description": "Path to the Python installation from which ty resolves type information and third-party dependencies.\n\nty will search in the path's `site-packages` directories for type information and third-party imports.\n\nThis option is commonly used to specify the path to a virtual environment.",
+          "description": "Path to your project's Python environment or interpreter.\n\nty 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.\n\nIf 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.\n\nPassing a path to a Python executable is supported, but passing a path to a dynamic executable (such as a shim) is not currently supported.\n\nThis option can be used to point to virtual or system Python environments.",
           "type": [
             "string",
             "null"