Generate API reference for options documentation (#5072)

## Summary

Generates Markdown from the `OptionsMetadata`, following the same
strategy as in Ruff.

## Test Plan

`cargo dev generate-options-reference`

crates/uv-dev/Cargo.toml

@@ -29,9 +29,11 @@ uv-dispatch = { workspace = true }
 uv-distribution = { workspace = true, features = ["schemars"] }
 uv-git = { workspace = true }
 uv-installer = { workspace = true }
+uv-macros = { workspace = true }
+uv-options-metadata = { workspace = true }
+uv-python = { workspace = true }
 uv-resolver = { workspace = true }
 uv-settings = { workspace = true, features = ["schemars"] }
-uv-python = { workspace = true }
 uv-types = { workspace = true }
 
 # Any dependencies that are exclusively used in `uv-dev` should be listed as non-workspace
@@ -40,6 +42,7 @@ anstream = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true, features = ["derive", "wrap_help"] }
 fs-err = { workspace = true, features = ["tokio"] }
+itertools = { workspace = true }
 owo-colors = { workspace = true }
 poloto = { version = "19.1.2", optional = true }
 pretty_assertions = { version = "1.4.0" }
@@ -49,6 +52,7 @@ schemars = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 tagu = { version = "0.1.6", optional = true }
+textwrap = { workspace = true }
 tokio = { workspace = true }
 tracing = { workspace = true }
 tracing-durations-export = { workspace = true, features = ["plot"] }

crates/uv-dev/src/generate_json_schema.rs

@@ -6,7 +6,8 @@ use pretty_assertions::StrComparison;
 use schemars::{schema_for, JsonSchema};
 use serde::Deserialize;
 
-use uv_settings::Options;
+use uv_distribution::pyproject::ToolUv as WorkspaceOptions;
+use uv_settings::Options as SettingsOptions;
 
 use crate::ROOT_DIR;
 
@@ -16,11 +17,11 @@ use crate::ROOT_DIR;
 // The names and docstrings of this struct and the types it contains are used as `title` and
 // `description` in uv.schema.json, see https://github.com/SchemaStore/schemastore/blob/master/editor-features.md#title-as-an-expected-object-type
 /// Metadata and configuration for uv.
-struct ToolUv {
+struct CombinedOptions {
     #[serde(flatten)]
-    options: Options,
+    options: SettingsOptions,
     #[serde(flatten)]
-    dep_spec: uv_distribution::pyproject::ToolUv,
+    workspace: WorkspaceOptions,
 }
 
 #[derive(clap::Args)]
@@ -44,7 +45,7 @@ enum Mode {
 }
 
 pub(crate) fn main(args: &GenerateJsonSchemaArgs) -> Result<()> {
-    let schema = schema_for!(ToolUv);
+    let schema = schema_for!(CombinedOptions);
     let schema_string = serde_json::to_string_pretty(&schema).unwrap();
     let filename = "uv.schema.json";
     let schema_path = PathBuf::from(ROOT_DIR).join(filename);

crates/uv-dev/src/generate_options_reference.rs

@@ -0,0 +1,221 @@
+//! Generate a Markdown-compatible listing of configuration options for `pyproject.toml`.
+//!
+//! Based on: <https://github.com/astral-sh/ruff/blob/dc8db1afb08704ad6a788c497068b01edf8b460d/crates/ruff_dev/src/generate_options.rs>
+use std::fmt::Write;
+
+use itertools::Itertools;
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+use uv_distribution::pyproject::ToolUv as WorkspaceOptions;
+use uv_macros::OptionsMetadata;
+use uv_options_metadata::{OptionField, OptionSet, OptionsMetadata, Visit};
+use uv_settings::Options as SettingsOptions;
+
+#[derive(Deserialize, JsonSchema, OptionsMetadata)]
+#[serde(deny_unknown_fields)]
+#[allow(dead_code)]
+// The names and docstrings of this struct and the types it contains are used as `title` and
+// `description` in uv.schema.json, see https://github.com/SchemaStore/schemastore/blob/master/editor-features.md#title-as-an-expected-object-type
+/// Metadata and configuration for uv.
+struct CombinedOptions {
+    #[serde(flatten)]
+    options: SettingsOptions,
+    #[serde(flatten)]
+    workspace: WorkspaceOptions,
+}
+
+pub(crate) fn generate() -> String {
+    let mut output = String::new();
+
+    generate_set(
+        &mut output,
+        Set::Global(CombinedOptions::metadata()),
+        &mut Vec::new(),
+    );
+
+    output
+}
+
+fn generate_set(output: &mut String, set: Set, parents: &mut Vec<Set>) {
+    match &set {
+        Set::Global(_) => {
+            output.push_str("### Global\n");
+        }
+        Set::Named { name, .. } => {
+            let title = parents
+                .iter()
+                .filter_map(|set| set.name())
+                .chain(std::iter::once(name.as_str()))
+                .join(".");
+            writeln!(output, "#### `{title}`\n").unwrap();
+
+            if let Some(documentation) = set.metadata().documentation() {
+                output.push_str(documentation);
+                output.push('\n');
+                output.push('\n');
+            }
+        }
+    }
+
+    let mut visitor = CollectOptionsVisitor::default();
+    set.metadata().record(&mut visitor);
+
+    let (mut fields, mut sets) = (visitor.fields, visitor.groups);
+
+    fields.sort_unstable_by(|(name, _), (name2, _)| name.cmp(name2));
+    sets.sort_unstable_by(|(name, _), (name2, _)| name.cmp(name2));
+
+    parents.push(set);
+
+    // Generate the fields.
+    for (name, field) in &fields {
+        emit_field(output, name, field, parents.as_slice());
+        output.push_str("---\n\n");
+    }
+
+    // Generate all the sub-sets.
+    for (set_name, sub_set) in &sets {
+        generate_set(
+            output,
+            Set::Named {
+                name: set_name.to_string(),
+                set: *sub_set,
+            },
+            parents,
+        );
+    }
+
+    parents.pop();
+}
+
+enum Set {
+    Global(OptionSet),
+    Named { name: String, set: OptionSet },
+}
+
+impl Set {
+    fn name(&self) -> Option<&str> {
+        match self {
+            Set::Global(_) => None,
+            Set::Named { name, .. } => Some(name),
+        }
+    }
+
+    fn metadata(&self) -> &OptionSet {
+        match self {
+            Set::Global(set) => set,
+            Set::Named { set, .. } => set,
+        }
+    }
+}
+
+fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[Set]) {
+    let header_level = if parents.is_empty() { "####" } else { "#####" };
+    let parents_anchor = parents.iter().filter_map(|parent| parent.name()).join("_");
+
+    if parents_anchor.is_empty() {
+        output.push_str(&format!(
+            "{header_level} [`{name}`](#{name}) {{: #{name} }}\n"
+        ));
+    } else {
+        output.push_str(&format!(
+            "{header_level} [`{name}`](#{parents_anchor}_{name}) {{: #{parents_anchor}_{name} }}\n"
+        ));
+
+        // the anchor used to just be the name, but now it's the group name
+        // for backwards compatibility, we need to keep the old anchor
+        output.push_str(&format!("<span id=\"{name}\"></span>\n"));
+    }
+
+    output.push('\n');
+
+    if let Some(deprecated) = &field.deprecated {
+        output.push_str("!!! warning \"Deprecated\"\n");
+        output.push_str("    This option has been deprecated");
+
+        if let Some(since) = deprecated.since {
+            write!(output, " in {since}").unwrap();
+        }
+
+        output.push('.');
+
+        if let Some(message) = deprecated.message {
+            writeln!(output, " {message}").unwrap();
+        }
+
+        output.push('\n');
+    }
+
+    output.push_str(field.doc);
+    output.push_str("\n\n");
+    output.push_str(&format!("**Default value**: `{}`\n", field.default));
+    output.push('\n');
+    output.push_str(&format!("**Type**: `{}`\n", field.value_type));
+    output.push('\n');
+    output.push_str("**Example usage**:\n\n");
+    output.push_str(&format_tab(
+        "pyproject.toml",
+        &format_header(field.scope, parents, ConfigurationFile::PyprojectToml),
+        field.example,
+    ));
+    output.push_str(&format_tab(
+        "uv.toml",
+        &format_header(field.scope, parents, ConfigurationFile::UvToml),
+        field.example,
+    ));
+    output.push('\n');
+}
+
+fn format_tab(tab_name: &str, header: &str, content: &str) -> String {
+    format!(
+        "=== \"{}\"\n\n    ```toml\n    {}\n{}\n    ```\n",
+        tab_name,
+        header,
+        textwrap::indent(content, "    ")
+    )
+}
+
+/// Format the TOML header for the example usage for a given option.
+///
+/// For example: `[tool.uv.pip]`.
+fn format_header(scope: Option<&str>, parents: &[Set], configuration: ConfigurationFile) -> String {
+    let tool_parent = match configuration {
+        ConfigurationFile::PyprojectToml => Some("tool.uv"),
+        ConfigurationFile::UvToml => None,
+    };
+
+    let header = tool_parent
+        .into_iter()
+        .chain(parents.iter().filter_map(|parent| parent.name()))
+        .chain(scope)
+        .join(".");
+
+    if header.is_empty() {
+        String::new()
+    } else {
+        format!("[{header}]")
+    }
+}
+
+#[derive(Debug, Copy, Clone)]
+enum ConfigurationFile {
+    PyprojectToml,
+    UvToml,
+}
+
+#[derive(Default)]
+struct CollectOptionsVisitor {
+    groups: Vec<(String, OptionSet)>,
+    fields: Vec<(String, OptionField)>,
+}
+
+impl Visit for CollectOptionsVisitor {
+    fn record_set(&mut self, name: &str, group: OptionSet) {
+        self.groups.push((name.to_owned(), group));
+    }
+
+    fn record_field(&mut self, name: &str, field: OptionField) {
+        self.fields.push((name.to_owned(), field));
+    }
+}

crates/uv-dev/src/main.rs

@@ -44,6 +44,7 @@ mod build;
 mod clear_compile;
 mod compile;
 mod generate_json_schema;
+mod generate_options_reference;
 mod render_benchmarks;
 mod wheel_metadata;
 
@@ -61,6 +62,8 @@ enum Cli {
     ClearCompile(ClearCompileArgs),
     /// Generate JSON schema for the TOML configuration file.
     GenerateJSONSchema(GenerateJsonSchemaArgs),
+    /// Generate the options reference for the documentation.
+    GenerateOptionsReference,
     #[cfg(feature = "render")]
     /// Render the benchmarks.
     RenderBenchmarks(RenderBenchmarksArgs),
@@ -78,6 +81,7 @@ async fn run() -> Result<()> {
         Cli::Compile(args) => compile::compile(args).await?,
         Cli::ClearCompile(args) => clear_compile::clear_compile(&args)?,
         Cli::GenerateJSONSchema(args) => generate_json_schema::main(&args)?,
+        Cli::GenerateOptionsReference => println!("{}", generate_options_reference::generate()),
         #[cfg(feature = "render")]
         Cli::RenderBenchmarks(args) => render_benchmarks::render_benchmarks(&args)?,
     }

crates/uv-distribution/Cargo.toml

@@ -26,7 +26,9 @@ uv-configuration = { workspace = true }
 uv-extract = { workspace = true }
 uv-fs = { workspace = true, features = ["tokio"] }
 uv-git = { workspace = true }
+uv-macros = { workspace = true }
 uv-normalize = { workspace = true }
+uv-options-metadata = { workspace = true }
 uv-types = { workspace = true }
 uv-warnings = { workspace = true }
 
@@ -61,3 +63,6 @@ regex = { workspace = true }
 
 [features]
 schemars = ["dep:schemars"]
+
+[package.metadata.cargo-shear]
+ignored = ["uv-options-metadata"]

crates/uv-distribution/src/pyproject.rs

@@ -17,6 +17,7 @@ use url::Url;
 use pep440_rs::VersionSpecifiers;
 use pypi_types::{RequirementSource, VerbatimParsedUrl};
 use uv_git::GitReference;
+use uv_macros::OptionsMetadata;
 use uv_normalize::{ExtraName, PackageName};
 
 /// A `pyproject.toml` as specified in PEP 517.
@@ -69,15 +70,23 @@ pub struct Tool {
     pub uv: Option<ToolUv>,
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, OptionsMetadata, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct ToolUv {
     pub sources: Option<BTreeMap<PackageName, Source>>,
     /// 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
     /// `uv run` is invoked.
+    #[option(
+        default = r#"true"#,
+        value_type = "bool",
+        example = r#"
+            managed = false
+        "#
+    )]
     pub managed: Option<bool>,
     #[cfg_attr(
         feature = "schemars",
@@ -97,10 +106,35 @@ pub struct ToolUv {
     pub override_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,
 }
 
-#[derive(Serialize, Deserialize, Default, Debug, Clone, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, OptionsMetadata, Default, Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct ToolUvWorkspace {
+    /// Packages to include as workspace members.
+    ///
+    /// Supports both globs and explicit paths.
+    ///
+    /// For more information on the glob syntax, refer to the [`glob` documentation](https://docs.rs/glob/latest/glob/struct.Pattern.html).
+    #[option(
+        default = r#"[]"#,
+        value_type = "list[str]",
+        example = r#"
+            members = ["member1", "path/to/member2", "libs/*"]
+        "#
+    )]
     pub members: Option<Vec<SerdePattern>>,
+    /// Packages to exclude as workspace members. If a package matches both `members` and
+    /// `exclude`, it will be excluded.
+    ///
+    /// Supports both globs and explicit paths.
+    ///
+    /// For more information on the glob syntax, refer to the [`glob` documentation](https://docs.rs/glob/latest/glob/struct.Pattern.html).
+    #[option(
+        default = r#"[]"#,
+        value_type = "list[str]",
+        example = r#"
+            exclude = ["member1", "path/to/member2", "libs/*"]
+        "#
+    )]
     pub exclude: Option<Vec<SerdePattern>>,
 }
 

crates/uv-macros/src/options_metadata.rs

@@ -91,8 +91,8 @@ pub(crate) fn derive_impl(input: DeriveInput) -> syn::Result<TokenStream> {
 
             Ok(quote! {
                 #[automatically_derived]
-                impl crate::options_base::OptionsMetadata for #ident {
-                    fn record(visit: &mut dyn crate::options_base::Visit) {
+                impl uv_options_metadata::OptionsMetadata for #ident {
+                    fn record(visit: &mut dyn uv_options_metadata::Visit) {
                         #(#output);*
                     }
 
@@ -130,7 +130,7 @@ fn handle_option_group(field: &Field) -> syn::Result<proc_macro2::TokenStream> {
                 let kebab_name = LitStr::new(&ident.to_string().replace('_', "-"), ident.span());
 
                 Ok(quote_spanned!(
-                    ident.span() => (visit.record_set(#kebab_name, crate::options_base::OptionSet::of::<#path>()))
+                    ident.span() => (visit.record_set(#kebab_name, uv_options_metadata::OptionSet::of::<#path>()))
                 ))
             }
             _ => Err(syn::Error::new(
@@ -219,14 +219,14 @@ fn handle_option(field: &Field, attr: &Attribute) -> syn::Result<proc_macro2::To
         let note = quote_option(deprecated.note);
         let since = quote_option(deprecated.since);
 
-        quote!(Some(crate::options_base::Deprecated { since: #since, message: #note }))
+        quote!(Some(uv_options_metadata::Deprecated { since: #since, message: #note }))
     } else {
         quote!(None)
     };
 
     Ok(quote_spanned!(
         ident.span() => {
-            visit.record_field(#kebab_name, crate::options_base::OptionField{
+            visit.record_field(#kebab_name, uv_options_metadata::OptionField{
                 doc: &#doc,
                 default: &#default,
                 value_type: &#value_type,

crates/uv-options-metadata/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "uv-options-metadata"
+version = "0.0.1"
+edition = { workspace = true }
+rust-version = { workspace = true }
+homepage = { workspace = true }
+documentation = { workspace = true }
+repository = { workspace = true }
+authors = { workspace = true }
+license = { workspace = true }
+
+[lints]
+workspace = true
+
+[dependencies]
+serde = { workspace = true }

crates/uv-options-metadata/src/lib.rs

@@ -1,6 +1,6 @@
 //! Taken directly from Ruff.
 //!
-//! See: <https://github.com/astral-sh/ruff/blob/dc8db1afb08704ad6a788c497068b01edf8b460d/crates/ruff_workspace/src/options_base.rs>
+//! See: <https://github.com/astral-sh/ruff/blob/dc8db1afb08704ad6a788c497068b01edf8b460d/crates/ruff_workspace/sr.rs>
 
 use serde::{Serialize, Serializer};
 use std::collections::BTreeMap;
@@ -106,7 +106,7 @@ impl OptionSet {
     /// ### Test for the existence of a child option
     ///
     /// ```rust
-    /// # use uv_settings::options_base::{OptionField, OptionsMetadata, Visit};
+    /// # use uv_options_metadata::{OptionField, OptionsMetadata, Visit};
     ///
     /// struct WithOptions;
     ///
@@ -129,7 +129,7 @@ impl OptionSet {
     /// ### Test for the existence of a nested option
     ///
     /// ```rust
-    /// # use uv_settings::options_base::{OptionField, OptionsMetadata, Visit};
+    /// # use uv_options_metadata::{OptionField, OptionsMetadata, Visit};
     ///
     /// struct Root;
     ///
@@ -180,7 +180,7 @@ impl OptionSet {
     /// ### Find a child option
     ///
     /// ```rust
-    /// # use uv_settings::options_base::{OptionEntry, OptionField, OptionsMetadata, Visit};
+    /// # use uv_options_metadata::{OptionEntry, OptionField, OptionsMetadata, Visit};
     ///
     /// struct WithOptions;
     ///
@@ -205,7 +205,7 @@ impl OptionSet {
     /// ### Find a nested option
     ///
     /// ```rust
-    /// # use uv_settings::options_base::{OptionEntry, OptionField, OptionsMetadata, Visit};
+    /// # use uv_options_metadata::{OptionEntry, OptionField, OptionsMetadata, Visit};
     ///
     /// static HARD_TABS: OptionField = OptionField {
     ///     doc: "Use hard tabs for indentation and spaces for alignment.",

crates/uv-settings/Cargo.toml

@@ -21,8 +21,9 @@ uv-configuration = { workspace = true, features = ["schemars"] }
 uv-fs = { workspace = true }
 uv-macros = { workspace = true }
 uv-normalize = { workspace = true, features = ["schemars"] }
-uv-resolver = { workspace = true, features = ["schemars"] }
+uv-options-metadata = { workspace = true }
 uv-python = { workspace = true, features = ["schemars"] }
+uv-resolver = { workspace = true, features = ["schemars"] }
 uv-warnings = { workspace = true }
 
 dirs-sys = { workspace = true }
@@ -32,3 +33,6 @@ serde = { workspace = true }
 thiserror = { workspace = true }
 toml = { workspace = true }
 tracing = { workspace = true }
+
+[package.metadata.cargo-shear]
+ignored = ["uv-options-metadata"]

crates/uv-settings/src/lib.rs

@@ -10,7 +10,6 @@ pub use crate::combine::*;
 pub use crate::settings::*;
 
 mod combine;
-pub mod options_base;
 mod settings;
 
 /// The [`Options`] as loaded from a configuration file on disk.

crates/uv-settings/src/settings.rs

@@ -30,7 +30,7 @@ pub(crate) struct Tools {
 
 /// A `[tool.uv]` section.
 #[allow(dead_code)]
-#[derive(Debug, Clone, Default, Deserialize, CombineOptions)]
+#[derive(Debug, Clone, Default, Deserialize, CombineOptions, OptionsMetadata)]
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Options {
@@ -38,6 +38,7 @@ pub struct Options {
     pub globals: GlobalOptions,
     #[serde(flatten)]
     pub top_level: ResolverInstallerOptions,
+    #[option_group]
     pub pip: Option<PipOptions>,
     #[cfg_attr(
         feature = "schemars",
@@ -120,6 +121,20 @@ pub struct ResolverOptions {
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct ResolverInstallerOptions {
+    /// The URL of the Python package index (by default: <https://pypi.org/simple>).
+    ///
+    /// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
+    /// directory laid out in the same format.
+    ///
+    /// The index provided by this setting is given lower priority than any indexes specified via
+    /// [`extra_index_url`](#extra-index-url).
+    #[option(
+        default = "https://pypi.org/simple",
+        value_type = "str",
+        example = r#"
+            index-url = "https://pypi.org/simple"
+        "#
+    )]
     pub index_url: Option<IndexUrl>,
     pub extra_index_url: Option<Vec<IndexUrl>>,
     pub no_index: Option<bool>,