Improve the uv venv CLI documentation (#5963)

This was actually in pretty good shape already!

crates/uv-cli/src/lib.rs

@@ -298,6 +298,16 @@ pub enum Commands {
     )]
     Pip(PipNamespace),
     /// Create a virtual environment.
+    ///
+    /// By default, creates a virtual environment named `.venv` in the working
+    /// directory. An alternative path may be provided positionally.
+    ///
+    /// If a virtual environment exists at the target path, it will be removed
+    /// and a new, empty virtual environment will be created.
+    ///
+    /// When using uv, the virtual environment does not need to be activated. uv
+    /// will find a virtual environment (named `.venv`) in the working directory
+    /// or any parent directories.
     #[command(
         alias = "virtualenv",
         alias = "v",
@@ -1887,13 +1897,13 @@ pub struct VenvArgs {
 
     /// Provide an alternative prompt prefix for the virtual environment.
     ///
-    /// The default behavior depends on whether the virtual environment path is provided:
-    /// - If provided (`uv venv project`), the prompt is set to the virtual environment's directory name.
-    /// - If not provided (`uv venv`), the prompt is set to the current directory's name.
+    /// By default, the prompt is dependent on whether a path was provided to
+    /// `uv venv`. If provided (e.g, `uv venv project`), the prompt is set to
+    /// the directory name. If not provided (`uv venv`), the prompt is set to
+    /// the current directory's name.
     ///
-    /// Possible values:
-    /// - `.`: Use the current directory name.
-    /// - Any string: Use the given string.
+    /// If "." is provided, the the current directory name will be used
+    /// regardless of whether a path was provided to `uv venv`.
     #[arg(long, verbatim_doc_comment)]
     pub prompt: Option<String>,
 
@@ -1902,7 +1912,7 @@ pub struct VenvArgs {
     /// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, uv will
     /// _not_ take system site packages into account when running commands like `uv pip list` or
     /// `uv pip install`. The `--system-site-packages` flag will provide the virtual environment
-    /// with access to the system site packages directory at runtime, but it will not affect the
+    /// with access to the system site packages directory at runtime, but will not affect the
     /// behavior of uv commands.
     #[arg(long)]
     pub system_site_packages: bool,

docs/reference/cli.md

@@ -5273,7 +5273,13 @@ uv pip check [OPTIONS]
 
 ## uv venv
 
-Create a virtual environment
+Create a virtual environment.
+
+By default, creates a virtual environment named `.venv` in the working directory. An alternative path may be provided positionally.
+
+If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.
+
+When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named `.venv`) in the working directory or any parent directories.
 
 <h3 class="cli-reference">Usage</h3>
 
@@ -5406,21 +5412,9 @@ uv venv [OPTIONS] [NAME]
 
 </dd><dt><code>--prompt</code> <i>prompt</i></dt><dd><p>Provide an alternative prompt prefix for the virtual environment.</p>
 
-<p>The default behavior depends on whether the virtual environment path is provided:</p>
-
-<ul>
-<li>If provided (<code>uv venv project</code>), the prompt is set to the virtual environment&#8217;s directory name.</li>
-
-<li>If not provided (<code>uv venv</code>), the prompt is set to the current directory&#8217;s name.</li>
-</ul>
-
-<p>Possible values:</p>
+<p>By default, the prompt is dependent on whether a path was provided to <code>uv venv</code>. If provided (e.g, <code>uv venv project</code>), the prompt is set to the directory name. If not provided (<code>uv venv</code>), the prompt is set to the current directory&#8217;s name.</p>
 
-<ul>
-<li><code>.</code>: Use the current directory name.</li>
-
-<li>Any string: Use the given string.</li>
-</ul>
+<p>If &quot;.&quot; is provided, the the current directory name will be used regardless of whether a path was provided to <code>uv venv</code>.</p>
 
 </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for the virtual environment.</p>
 
@@ -5468,7 +5462,7 @@ uv venv [OPTIONS] [NAME]
 
 </dd><dt><code>--system-site-packages</code></dt><dd><p>Give the virtual environment access to the system site packages directory.</p>
 
-<p>Unlike <code>pip</code>, when a virtual environment is created with <code>--system-site-packages</code>, uv will <em>not</em> take system site packages into account when running commands like <code>uv pip list</code> or <code>uv pip install</code>. The <code>--system-site-packages</code> flag will provide the virtual environment with access to the system site packages directory at runtime, but it will not affect the behavior of uv commands.</p>
+<p>Unlike <code>pip</code>, when a virtual environment is created with <code>--system-site-packages</code>, uv will <em>not</em> take system site packages into account when running commands like <code>uv pip list</code> or <code>uv pip install</code>. The <code>--system-site-packages</code> flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.</p>
 
 </dd><dt><code>--verbose</code>, <code>-v</code></dt><dd><p>Use verbose output.</p>