Add reference documentation for global settings (#5123)

## Summary

Second part of: #5093.

crates/uv-cache/src/cli.rs

@@ -8,7 +8,8 @@ use crate::Cache;
 
 #[derive(Parser, Debug, Clone)]
 pub struct CacheArgs {
-    /// Avoid reading from or writing to the cache.
+    /// Avoid reading from or writing to the cache, instead using a temporary directory for the
+    /// duration of the operation.
     #[arg(
         global = true,
         long,

crates/uv-dev/src/main.rs

@@ -124,7 +124,7 @@ async fn main() -> ExitCode {
         (None, None)
     };
 
-    // Show `INFO` messages from the `uv` crate, but allow `RUST_LOG` to override.
+    // Show `INFO` messages from the uv crate, but allow `RUST_LOG` to override.
     let default_directive = Directive::from_str("uv=info").unwrap();
 
     let filter = EnvFilter::builder()

crates/uv-distribution/src/pyproject.rs

@@ -78,7 +78,7 @@ pub struct ToolUv {
     /// The workspace definition for the project, if any.
     #[option_group]
     pub workspace: Option<ToolUvWorkspace>,
-    /// Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when
+    /// Whether the project is managed by uv. If `false`, uv will ignore the project when
     /// `uv run` is invoked.
     #[option(
         default = r#"true"#,

crates/uv-installer/src/compile.rs

@@ -60,7 +60,7 @@ pub enum CompileError {
 /// We only compile all files, but we don't update the RECORD, relying on PEP 491:
 /// > Uninstallers should be smart enough to remove .pyc even if it is not mentioned in RECORD.
 ///
-/// We've confirmed that both `uv` and `pip` (as of 24.0.0) remove the `__pycache__` directory.
+/// We've confirmed that both uv and pip (as of 24.0.0) remove the `__pycache__` directory.
 #[instrument(skip(python_executable))]
 pub async fn compile_tree(
     dir: &Path,

crates/uv-python/src/virtualenv.rs

@@ -24,9 +24,9 @@ pub struct VirtualEnvironment {
 /// A parsed `pyvenv.cfg`
 #[derive(Debug, Clone)]
 pub struct PyVenvConfiguration {
-    /// If the `virtualenv` package was used to create the virtual environment.
+    /// If the virtualenv package was used to create the virtual environment.
     pub(crate) virtualenv: bool,
-    /// If the `uv` package was used to create the virtual environment.
+    /// If the uv package was used to create the virtual environment.
     pub(crate) uv: bool,
 }
 
@@ -165,7 +165,7 @@ impl PyVenvConfiguration {
         self.virtualenv
     }
 
-    /// Returns true if the virtual environment was created with the `uv` package.
+    /// Returns true if the virtual environment was created with the uv package.
     pub fn is_uv(&self) -> bool {
         self.uv
     }

crates/uv-settings/src/settings.rs

@@ -56,12 +56,81 @@ pub struct Options {
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct GlobalOptions {
+    /// Whether to load TLS certificates from the platform's native certificate store.
+    ///
+    /// By default, uv loads certificates from the bundled `webpki-roots` crate. The
+    /// `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in uv
+    /// improves portability and performance (especially on macOS).
+    ///
+    /// However, in some cases, you may want to use the platform's native certificate store,
+    /// especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's
+    /// included in your system's certificate store.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            native-tls = true
+        "#
+    )]
     pub native_tls: Option<bool>,
+    /// Disable network access, relying only on locally cached data and locally available files.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            offline = true
+        "#
+    )]
     pub offline: Option<bool>,
+    /// Avoid reading from or writing to the cache, instead using a temporary directory for the
+    /// duration of the operation.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            no-cache = true
+        "#
+    )]
     pub no_cache: Option<bool>,
+    /// Path to the cache directory.
+    ///
+    /// Defaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on
+    /// Linux, and `{FOLDERID_LocalAppData}\uv\cache` on Windows.
+    #[option(
+        default = "None",
+        value_type = "str",
+        example = r#"
+            cache-dir = "./.uv_cache"
+        "#
+    )]
     pub cache_dir: Option<PathBuf>,
+    /// Whether to enable experimental, preview features.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            preview = true
+        "#
+    )]
     pub preview: Option<bool>,
+    /// Whether to prefer using Python installations that are already present on the system, or
+    /// those that are downloaded and installed by uv.
+    #[option(
+        default = "\"installed\"",
+        value_type = "str",
+        example = r#"
+            python-preference = "managed"
+        "#
+    )]
     pub python_preference: Option<PythonPreference>,
+    /// Whether to automatically download Python when required.
+    #[option(
+        default = "\"automatic\"",
+        value_type = "str",
+        example = r#"
+            python-fetch = \"automatic\"
+        "#
+    )]
     pub python_fetch: Option<PythonFetch>,
 }
 
@@ -182,7 +251,7 @@ pub struct ResolverInstallerOptions {
     pub find_links: Option<Vec<FlatIndexLocation>>,
     /// The strategy to use when resolving against multiple index URLs.
     ///
-    /// By default, `uv` will stop at the first index on which a given package is available, and
+    /// By default, uv will stop at the first index on which a given package is available, and
     /// limit resolutions to those present on that first index (`first-match`). This prevents
     /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
     /// same name to a secondary.
@@ -202,7 +271,7 @@ pub struct ResolverInstallerOptions {
     pub index_strategy: Option<IndexStrategy>,
     /// Attempt to use `keyring` for authentication for index URLs.
     ///
-    /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
+    /// At present, only `--keyring-provider subprocess` is supported, which configures uv to
     /// use the `keyring` CLI to handle authentication.
     #[option(
         default = "\"disabled\"",
@@ -215,7 +284,7 @@ pub struct ResolverInstallerOptions {
     /// The strategy to use when selecting between the different compatible versions for a given
     /// package requirement.
     ///
-    /// By default, `uv` will use the latest compatible version of each package (`highest`).
+    /// By default, uv will use the latest compatible version of each package (`highest`).
     #[option(
         default = "\"highest\"",
         value_type = "str",
@@ -226,7 +295,7 @@ pub struct ResolverInstallerOptions {
     pub resolution: Option<ResolutionMode>,
     /// The strategy to use when considering pre-release versions.
     ///
-    /// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases,
+    /// By default, uv will accept pre-releases for packages that _only_ publish pre-releases,
     /// along with first-party requirements that contain an explicit pre-release marker in the
     /// declared specifiers (`if-necessary-or-explicit`).
     #[option(

crates/uv-types/src/lib.rs

@@ -1,4 +1,4 @@
-//! Fundamental types shared across `uv` crates.
+//! Fundamental types shared across uv crates.
 pub use builds::*;
 pub use downloads::*;
 pub use hash::*;

crates/uv/src/commands/pip/compile.rs

@@ -491,7 +491,7 @@ pub(crate) async fn pip_compile(
     Ok(ExitStatus::Success)
 }
 
-/// Format the `uv` command used to generate the output file.
+/// Format the uv command used to generate the output file.
 #[allow(clippy::fn_params_excessive_bools)]
 fn cmd(
     include_index_url: bool,

crates/uv/src/commands/self_update.rs

@@ -10,24 +10,24 @@ use uv_client::WrappedReqwestError;
 use crate::commands::ExitStatus;
 use crate::printer::Printer;
 
-/// Attempt to update the `uv` binary.
+/// Attempt to update the uv binary.
 pub(crate) async fn self_update(printer: Printer) -> Result<ExitStatus> {
     let mut updater = AxoUpdater::new_for("uv");
     updater.disable_installer_output();
 
     // Load the "install receipt" for the current binary. If the receipt is not found, then
-    // `uv` was likely installed via a package manager.
+    // uv was likely installed via a package manager.
     let Ok(updater) = updater.load_receipt() else {
-        debug!("no receipt found; assuming `uv` was installed via a package manager");
+        debug!("no receipt found; assuming uv was installed via a package manager");
         writeln!(
             printer.stderr(),
             "{}",
             format_args!(
                 concat!(
-                    "{}{} Self-update is only available for `uv` binaries installed via the standalone installation scripts.",
+                    "{}{} Self-update is only available for uv binaries installed via the standalone installation scripts.",
                     "\n",
                     "\n",
-                    "If you installed `uv` with `pip`, `brew`, or another package manager, update `uv` with `pip install --upgrade`, `brew upgrade`, or similar."
+                    "If you installed uv with pip, brew, or another package manager, update uv with `pip install --upgrade`, `brew upgrade`, or similar."
                 ),
                 "warning".yellow().bold(),
                 ":".bold()
@@ -37,21 +37,21 @@ pub(crate) async fn self_update(printer: Printer) -> Result<ExitStatus> {
     };
 
     // Ensure the receipt is for the current binary. If it's not, then the user likely has multiple
-    // `uv` binaries installed, and the current binary was _not_ installed via the standalone
+    // uv binaries installed, and the current binary was _not_ installed via the standalone
     // installation scripts.
     if !updater.check_receipt_is_for_this_executable()? {
         debug!(
-            "receipt is not for this executable; assuming `uv` was installed via a package manager"
+            "receipt is not for this executable; assuming uv was installed via a package manager"
         );
         writeln!(
             printer.stderr(),
             "{}",
             format_args!(
                 concat!(
-                    "{}{} Self-update is only available for `uv` binaries installed via the standalone installation scripts.",
+                    "{}{} Self-update is only available for uv binaries installed via the standalone installation scripts.",
                     "\n",
                     "\n",
-                    "If you installed `uv` with `pip`, `brew`, or another package manager, update `uv` with `pip install --upgrade`, `brew upgrade`, or similar."
+                    "If you installed uv with pip, brew, or another package manager, update uv with `pip install --upgrade`, `brew upgrade`, or similar."
                 ),
                 "warning".yellow().bold(),
                 ":".bold()
@@ -71,14 +71,14 @@ pub(crate) async fn self_update(printer: Printer) -> Result<ExitStatus> {
     )?;
 
     // Run the updater. This involves a network request, since we need to determine the latest
-    // available version of `uv`.
+    // available version of uv.
     match updater.run().await {
         Ok(Some(result)) => {
             writeln!(
                 printer.stderr(),
                 "{}",
                 format_args!(
-                    "{}{} Upgraded `uv` to {}! {}",
+                    "{}{} Upgraded uv to {}! {}",
                     "success".green().bold(),
                     ":".bold(),
                     format!("v{}", result.new_version).bold().white(),
@@ -95,7 +95,7 @@ pub(crate) async fn self_update(printer: Printer) -> Result<ExitStatus> {
                 printer.stderr(),
                 "{}",
                 format_args!(
-                    "{}{} You're on the latest version of `uv` ({}).",
+                    "{}{} You're on the latest version of uv ({}).",
                     "success".green().bold(),
                     ":".bold(),
                     format!("v{}", env!("CARGO_PKG_VERSION")).bold().white()

crates/uv/src/commands/tool/run.rs

@@ -411,7 +411,7 @@ fn parse_target(target: &OsString) -> Result<(Cow<OsString>, Cow<str>)> {
         return Err(anyhow::anyhow!("Tool command could not be parsed as UTF-8 string. Use `--from` to specify the package name."));
     };
 
-    // e.g. `uv`, no special handling
+    // e.g. uv, no special handling
     let Some((name, version)) = target_str.split_once('@') else {
         return Ok((Cow::Borrowed(target), Cow::Borrowed(target_str)));
     };

crates/uv/src/lib.rs

@@ -987,7 +987,7 @@ async fn run_project(
 /// The main entry point for a uv invocation.
 ///
 /// WARNING: This entry point is not recommended for external consumption, the
-/// `uv` binary interface is the official public API. When using this entry
+/// uv binary interface is the official public API. When using this entry
 /// point, uv assumes it is running in a process it controls and that the
 /// entire process lifetime is managed by uv. Unexpected behavior may be
 /// encountered if this entry pointis called multiple times in a single process.

crates/uv/src/settings.rs

@@ -1300,7 +1300,7 @@ impl VenvSettings {
     }
 }
 
-/// The resolved settings to use for an invocation of the `uv` CLI when installing dependencies.
+/// The resolved settings to use for an invocation of the uv CLI when installing dependencies.
 ///
 /// Combines the `[tool.uv]` persistent configuration with the command-line arguments
 /// ([`InstallerArgs`], represented as [`InstallerOptions`]).
@@ -1317,7 +1317,7 @@ pub(crate) struct InstallerSettingsRef<'a> {
     pub(crate) build_options: &'a BuildOptions,
 }
 
-/// The resolved settings to use for an invocation of the `uv` CLI when resolving dependencies.
+/// The resolved settings to use for an invocation of the uv CLI when resolving dependencies.
 ///
 /// Combines the `[tool.uv]` persistent configuration with the command-line arguments
 /// ([`ResolverArgs`], represented as [`ResolverOptions`]).
@@ -1446,10 +1446,10 @@ impl ResolverSettings {
     }
 }
 
-/// The resolved settings to use for an invocation of the `uv` CLI with both resolver and installer
+/// The resolved settings to use for an invocation of the uv CLI with both resolver and installer
 /// capabilities.
 ///
-/// Represents the shared settings that are used across all `uv` commands outside the `pip` API.
+/// Represents the shared settings that are used across all uv commands outside the `pip` API.
 /// Analogous to the settings contained in the `[tool.uv]` table, combined with [`ResolverInstallerArgs`].
 #[allow(clippy::struct_excessive_bools)]
 #[derive(Debug, Clone, Default)]

crates/uv/tests/common/mod.rs

@@ -313,7 +313,7 @@ impl TestContext {
         }
     }
 
-    /// Create a `uv` command for testing.
+    /// Create a uv command for testing.
     pub fn command(&self) -> Command {
         let mut command = Command::new(get_bin());
         self.add_shared_args(&mut command);