Fix depth of settings headers (#5103)

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

crates/uv-dev/src/generate_options_reference.rs

@@ -105,7 +105,7 @@ fn generate() -> String {
 fn generate_set(output: &mut String, set: Set, parents: &mut Vec<Set>) {
     match &set {
         Set::Global(_) => {
-            output.push_str("### Global\n");
+            output.push_str("## Global\n");
         }
         Set::Named { name, .. } => {
             let title = parents
@@ -113,7 +113,7 @@ fn generate_set(output: &mut String, set: Set, parents: &mut Vec<Set>) {
                 .filter_map(|set| set.name())
                 .chain(std::iter::once(name.as_str()))
                 .join(".");
-            writeln!(output, "#### `{title}`\n").unwrap();
+            writeln!(output, "## `{title}`\n").unwrap();
 
             if let Some(documentation) = set.metadata().documentation() {
                 output.push_str(documentation);
@@ -176,7 +176,7 @@ impl Set {
 }
 
 fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[Set]) {
-    let header_level = if parents.is_empty() { "####" } else { "#####" };
+    let header_level = if parents.is_empty() { "###" } else { "####" };
     let parents_anchor = parents.iter().filter_map(|parent| parent.name()).join("_");
 
     if parents_anchor.is_empty() {

crates/uv-settings/src/settings.rs

@@ -157,7 +157,10 @@ pub struct ResolverInstallerOptions {
     pub no_binary_package: Option<Vec<PackageName>>,
 }
 
-/// A `[tool.uv.pip]` section.
+/// Settings that are specific to the `uv pip` command-line interface.
+///
+/// These values will be ignored when running commands outside the `uv pip` namespace (e.g.,
+/// `uv lock`, `uvx`).
 #[allow(dead_code)]
 #[derive(Debug, Clone, Default, Deserialize, CombineOptions, OptionsMetadata)]
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]

docs/settings.md

@@ -1,5 +1,5 @@
-### Global
-##### [`index-url`](#index-url) {: #index-url }
+## Global
+#### [`index-url`](#index-url) {: #index-url }
 
 The URL of the Python package index (by default: <https://pypi.org/simple>).
 
@@ -30,7 +30,7 @@ The index provided by this setting is given lower priority than any indexes spec
 
 ---
 
-##### [`managed`](#managed) {: #managed }
+#### [`managed`](#managed) {: #managed }
 
 Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when
 `uv run` is invoked.
@@ -56,11 +56,14 @@ Whether the project is managed by `uv`. If `false`, `uv` will ignore the project
 
 ---
 
-#### `pip`
+## `pip`
 
-A `[tool.uv.pip]` section.
+Settings that are specific to the `uv pip` command-line interface.
 
-##### [`no-header`](#pip_no-header) {: #pip_no-header }
+These values will be ignored when running commands outside the `uv pip` namespace (e.g.,
+`uv lock`, `uvx`).
+
+#### [`no-header`](#pip_no-header) {: #pip_no-header }
 <span id="no-header"></span>
 
 Exclude the comment header at the top of output file generated by `uv pip compile`.
@@ -86,9 +89,9 @@ Exclude the comment header at the top of output file generated by `uv pip compil
 
 ---
 
-#### `workspace`
+## `workspace`
 
-##### [`exclude`](#workspace_exclude) {: #workspace_exclude }
+#### [`exclude`](#workspace_exclude) {: #workspace_exclude }
 <span id="exclude"></span>
 
 Packages to exclude as workspace members. If a package matches both `members` and
@@ -119,7 +122,7 @@ For more information on the glob syntax, refer to the [`glob` documentation](htt
 
 ---
 
-##### [`members`](#workspace_members) {: #workspace_members }
+#### [`members`](#workspace_members) {: #workspace_members }
 <span id="members"></span>
 
 Packages to include as workspace members.

uv.schema.json

@@ -441,7 +441,7 @@
       "pattern": "^(:none:|:all:|([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]))$"
     },
     "PipOptions": {
-      "description": "A `[tool.uv.pip]` section.",
+      "description": "Settings that are specific to the `uv pip` command-line interface.\n\nThese values will be ignored when running commands outside the `uv pip` namespace (e.g., `uv lock`, `uvx`).",
       "type": "object",
       "properties": {
         "all-extras": {