Add `tool.uv.sources` to the "Settings" reference (#8543)

## Summary

Closes https://github.com/astral-sh/uv/issues/8540.

crates/uv-dev/src/generate_cli_reference.rs

@@ -101,7 +101,14 @@ fn generate() -> String {
     generate_command(&mut output, &uv, &mut parents);
 
     for (value, replacement) in REPLACEMENTS {
-        output = output.replace(value, replacement);
+        assert_ne!(
+            value, replacement,
+            "`value` and `replacement` must be different, but both are `{value}`"
+        );
+        let before = &output;
+        let after = output.replace(value, replacement);
+        assert_ne!(*before, after, "Could not find `{value}` in the output");
+        output = after;
     }
 
     output

crates/uv-dev/src/generate_json_schema.rs

@@ -33,8 +33,8 @@ pub(crate) struct Args {
 }
 
 pub(crate) fn main(args: &Args) -> Result<()> {
-    let schema = schema_for!(CombinedOptions);
-    let schema_string = serde_json::to_string_pretty(&schema).unwrap();
+    // Generate the schema.
+    let schema_string = generate();
     let filename = "uv.schema.json";
     let schema_path = PathBuf::from(ROOT_DIR).join(filename);
 
@@ -80,5 +80,32 @@ pub(crate) fn main(args: &Args) -> Result<()> {
     Ok(())
 }
 
+const REPLACEMENTS: &[(&str, &str)] = &[
+    // Use the fully-resolved URL rather than the relative Markdown path.
+    (
+        "(../concepts/dependencies.md)",
+        "(https://docs.astral.sh/uv/concepts/dependencies/)",
+    ),
+];
+
+/// Generate the JSON schema for the combined options as a string.
+fn generate() -> String {
+    let schema = schema_for!(CombinedOptions);
+    let mut output = serde_json::to_string_pretty(&schema).unwrap();
+
+    for (value, replacement) in REPLACEMENTS {
+        assert_ne!(
+            value, replacement,
+            "`value` and `replacement` must be different, but both are `{value}`"
+        );
+        let before = &output;
+        let after = output.replace(value, replacement);
+        assert_ne!(*before, after, "Could not find `{value}` in the output");
+        output = after;
+    }
+
+    output
+}
+
 #[cfg(test)]
 mod tests;

crates/uv-workspace/src/pyproject.rs

@@ -152,8 +152,23 @@ pub struct Tool {
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct ToolUv {
-    /// The sources to use (e.g., workspace members, Git repositories, local paths) when resolving
-    /// dependencies.
+    /// The sources to use when resolving dependencies.
+    ///
+    /// `tool.uv.sources` enriches the dependency metadata with additional sources, incorporated
+    /// during development. A dependency source can be a Git repository, a URL, a local path, or an
+    /// alternative registry.
+    ///
+    /// See [Dependencies](../concepts/dependencies.md) for more.
+    #[option(
+        default = "\"[]\"",
+        value_type = "dict",
+        example = r#"
+            [tool.uv.sources]
+            httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
+            pytest =  { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
+            pydantic = { path = "/path/to/pydantic", editable = true }
+        "#
+    )]
     pub sources: Option<ToolUvSources>,
 
     /// The indexes to use when resolving dependencies.

docs/reference/settings.md

@@ -198,6 +198,32 @@ package = false
 
 ---
 
+### [`sources`](#sources) {: #sources }
+
+The sources to use when resolving dependencies.
+
+`tool.uv.sources` enriches the dependency metadata with additional sources, incorporated
+during development. A dependency source can be a Git repository, a URL, a local path, or an
+alternative registry.
+
+See [Dependencies](../concepts/dependencies.md) for more.
+
+**Default value**: `"[]"`
+
+**Type**: `dict`
+
+**Example usage**:
+
+```toml title="pyproject.toml"
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
+pytest =  { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
+pydantic = { path = "/path/to/pydantic", editable = true }
+```
+
+---
+
 ### `workspace`
 
 #### [`exclude`](#workspace_exclude) {: #workspace_exclude }

uv.schema.json

@@ -398,7 +398,7 @@
       ]
     },
     "sources": {
-      "description": "The sources to use (e.g., workspace members, Git repositories, local paths) when resolving dependencies.",
+      "description": "The sources to use when resolving dependencies.\n\n`tool.uv.sources` enriches the dependency metadata with additional sources, incorporated during development. A dependency source can be a Git repository, a URL, a local path, or an alternative registry.\n\nSee [Dependencies](https://docs.astral.sh/uv/concepts/dependencies/) for more.",
       "anyOf": [
         {
           "$ref": "#/definitions/ToolUvSources"