Improve some env var document (#10887)

crates/uv-static/src/env_vars.rs

@@ -52,6 +52,7 @@ impl EnvVars {
 
     /// Equivalent to the `--system` command-line argument. If set to `true`, uv will
     /// use the first Python interpreter found in the system `PATH`.
+    ///
     /// WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI)
     /// or containerized environments and should be used with caution, as modifying the system
     /// Python can lead to unexpected behavior.
@@ -63,6 +64,7 @@ impl EnvVars {
 
     /// Equivalent to the `--break-system-packages` command-line argument. If set to `true`,
     /// uv will allow the installation of packages that conflict with system-installed packages.
+    ///
     /// WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
     /// (CI) or containerized environments and should be used with caution, as modifying the system
     /// Python can lead to unexpected behavior.
@@ -72,9 +74,11 @@ impl EnvVars {
     /// use the system's trust store instead of the bundled `webpki-roots` crate.
     pub const UV_NATIVE_TLS: &'static str = "UV_NATIVE_TLS";
 
-    /// Equivalent to the `--index-strategy` command-line argument. For example, if
+    /// Equivalent to the `--index-strategy` command-line argument.
-    /// set to `unsafe-any-match`, uv will consider versions of a given package available across all index
+    ///
-    /// URLs, rather than limiting its search to the first index URL that contains the package.
+    /// For example, if set to `unsafe-any-match`, uv will consider versions of a given package
+    /// available across all index URLs, rather than limiting its search to the first index URL
+    /// that contains the package.
     pub const UV_INDEX_STRATEGY: &'static str = "UV_INDEX_STRATEGY";
 
     /// Equivalent to the `--require-hashes` command-line argument. If set to `true`,
@@ -102,6 +106,7 @@ impl EnvVars {
     pub const UV_NO_BUILD_ISOLATION: &'static str = "UV_NO_BUILD_ISOLATION";
 
     /// Equivalent to the `--custom-compile-command` command-line argument.
+    ///
     /// Used to override uv in the output header of the `requirements.txt` files generated by
     /// `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper
     /// script, to include the name of the wrapper script in the output file.
@@ -208,6 +213,7 @@ impl EnvVars {
     pub const UV_TOOL_BIN_DIR: &'static str = "UV_TOOL_BIN_DIR";
 
     /// Specifies the path to the directory to use for a project virtual environment.
+    ///
     /// See the [project documentation](../concepts/projects/config.md#project-environment-path)
     /// for more details.
     pub const UV_PROJECT_ENVIRONMENT: &'static str = "UV_PROJECT_ENVIRONMENT";
@@ -220,14 +226,16 @@ impl EnvVars {
 
     /// Managed Python installations are downloaded from the Astral
     /// [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project.
+    ///
     /// This variable can be set to a mirror URL to use a different source for Python installations.
     /// The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g.,
     /// `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
     /// Distributions can be read from a local directory by using the `file://` URL scheme.
     pub const UV_PYTHON_INSTALL_MIRROR: &'static str = "UV_PYTHON_INSTALL_MIRROR";
 
-    /// Managed PyPy installations are downloaded from
+    /// Managed PyPy installations are downloaded from [python.org](https://downloads.python.org/).
-    /// [python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a
+    ///
+    /// This variable can be set to a mirror URL to use a
     /// different source for PyPy installations. The provided URL will replace
     /// `https://downloads.python.org/pypy` in, e.g.,
     /// `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
@@ -255,13 +263,19 @@ impl EnvVars {
     /// Use to disable line wrapping for diagnostics.
     pub const UV_NO_WRAP: &'static str = "UV_NO_WRAP";
 
-    /// Generates the environment variable key for the HTTP Basic authentication username.
+    /// Provides the HTTP Basic authentication username for a named index.
+    ///
+    /// The `name` parameter is the name of the index. For example, given an index named `foo`,
+    /// the environment variable key would be `UV_INDEX_FOO_USERNAME`.
     #[attr_env_var_pattern("UV_INDEX_{name}_USERNAME")]
     pub fn index_username(name: &str) -> String {
         format!("UV_INDEX_{name}_USERNAME")
     }
 
-    /// Generates the environment variable key for the HTTP Basic authentication password.
+    /// Provides the HTTP Basic authentication password for a named index.
+    ///
+    /// The `name` parameter is the name of the index. For example, given an index named `foo`,
+    /// the environment variable key would be `UV_INDEX_FOO_PASSWORD`.
     #[attr_env_var_pattern("UV_INDEX_{name}_PASSWORD")]
     pub fn index_password(name: &str) -> String {
         format!("UV_INDEX_{name}_PASSWORD")
@@ -500,6 +514,7 @@ impl EnvVars {
 
     /// If set, uv will use this value as the log level for its `--verbose` output. Accepts
     /// any filter compatible with the `tracing_subscriber` crate.
+    ///
     /// For example:
     /// * `RUST_LOG=uv=debug` is the equivalent of adding `--verbose` to the command line
     /// * `RUST_LOG=trace` will enable trace-level logging.

docs/configuration/environment.md

@@ -6,6 +6,7 @@ uv defines and respects the following environment variables:
 
 Equivalent to the `--break-system-packages` command-line argument. If set to `true`,
 uv will allow the installation of packages that conflict with system-installed packages.
+
 WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
 (CI) or containerized environments and should be used with caution, as modifying the system
 Python can lead to unexpected behavior.
@@ -53,6 +54,7 @@ file as the constraints file. Uses space-separated list of files.
 ### `UV_CUSTOM_COMPILE_COMMAND`
 
 Equivalent to the `--custom-compile-command` command-line argument.
+
 Used to override uv in the output header of the `requirements.txt` files generated by
 `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper
 script, to include the name of the wrapper script in the output file.
@@ -111,9 +113,11 @@ space-separated list of URLs as additional indexes when searching for packages.
 
 ### `UV_INDEX_STRATEGY`
 
-Equivalent to the `--index-strategy` command-line argument. For example, if
+Equivalent to the `--index-strategy` command-line argument.
-set to `unsafe-any-match`, uv will consider versions of a given package available across all index
+
-URLs, rather than limiting its search to the first index URL that contains the package.
+For example, if set to `unsafe-any-match`, uv will consider versions of a given package
+available across all index URLs, rather than limiting its search to the first index URL
+that contains the package.
 
 ### `UV_INDEX_URL`
 
@@ -123,11 +127,17 @@ URL as the default index when searching for packages.
 
 ### `UV_INDEX_{name}_PASSWORD`
 
-Generates the environment variable key for the HTTP Basic authentication password.
+Provides the HTTP Basic authentication password for a named index.
+
+The `name` parameter is the name of the index. For example, given an index named `foo`,
+the environment variable key would be `UV_INDEX_FOO_PASSWORD`.
 
 ### `UV_INDEX_{name}_USERNAME`
 
-Generates the environment variable key for the HTTP Basic authentication username.
+Provides the HTTP Basic authentication username for a named index.
+
+The `name` parameter is the name of the index. For example, given an index named `foo`,
+the environment variable key would be `UV_INDEX_FOO_USERNAME`.
 
 ### `UV_INSECURE_HOST`
 
@@ -232,6 +242,7 @@ Equivalent to the `--preview` argument. Enables preview mode.
 ### `UV_PROJECT_ENVIRONMENT`
 
 Specifies the path to the directory to use for a project virtual environment.
+
 See the [project documentation](../concepts/projects/config.md#project-environment-path)
 for more details.
 
@@ -266,8 +277,9 @@ set, uv will use this username for publishing.
 
 ### `UV_PYPY_INSTALL_MIRROR`
 
-Managed PyPy installations are downloaded from
+Managed PyPy installations are downloaded from [python.org](https://downloads.python.org/).
-[python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a
+
+This variable can be set to a mirror URL to use a
 different source for PyPy installations. The provided URL will replace
 `https://downloads.python.org/pypy` in, e.g.,
 `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
@@ -296,6 +308,7 @@ Specifies the directory for storing managed Python installations.
 
 Managed Python installations are downloaded from the Astral
 [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project.
+
 This variable can be set to a mirror URL to use a different source for Python installations.
 The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g.,
 `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
@@ -324,6 +337,7 @@ Equivalent to the `--resolution` command-line argument. For example, if set to
 
 Equivalent to the `--system` command-line argument. If set to `true`, uv will
 use the first Python interpreter found in the system `PATH`.
+
 WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI)
 or containerized environments and should be used with caution, as modifying the system
 Python can lead to unexpected behavior.
@@ -480,6 +494,7 @@ Adds directories to Python module search path (e.g., `PYTHONPATH=/path/to/module
 
 If set, uv will use this value as the log level for its `--verbose` output. Accepts
 any filter compatible with the `tracing_subscriber` crate.
+
 For example:
 * `RUST_LOG=uv=debug` is the equivalent of adding `--verbose` to the command line
 * `RUST_LOG=trace` will enable trace-level logging.