From 8e13765b573f00b3156368a569c8a0b5bcf92332 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Mon, 15 Dec 2025 15:36:08 -0600 Subject: [PATCH] [ty] Use `title` for configuration code fences in ty reference documentation (#21992) Part of https://github.com/astral-sh/ty/pull/1904 --- crates/ruff_dev/src/generate_ty_options.rs | 9 +-- crates/ty/docs/configuration.md | 64 +++++++++++----------- 2 files changed, 37 insertions(+), 36 deletions(-) diff --git a/crates/ruff_dev/src/generate_ty_options.rs b/crates/ruff_dev/src/generate_ty_options.rs index 733af8b00a..6322f65981 100644 --- a/crates/ruff_dev/src/generate_ty_options.rs +++ b/crates/ruff_dev/src/generate_ty_options.rs @@ -166,8 +166,9 @@ fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[S output.push('\n'); let _ = writeln!(output, "**Type**: `{}`", field.value_type); output.push('\n'); - output.push_str("**Example usage** (`pyproject.toml`):\n\n"); + output.push_str("**Example usage**:\n\n"); output.push_str(&format_example( + "pyproject.toml", &format_header( field.scope, field.example, @@ -179,11 +180,11 @@ fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[S output.push('\n'); } -fn format_example(header: &str, content: &str) -> String { +fn format_example(title: &str, header: &str, content: &str) -> String { if header.is_empty() { - format!("```toml\n{content}\n```\n",) + format!("```toml title=\"{title}\"\n{content}\n```\n",) } else { - format!("```toml\n{header}\n{content}\n```\n",) + format!("```toml title=\"{title}\"\n{header}\n{content}\n```\n",) } } diff --git a/crates/ty/docs/configuration.md b/crates/ty/docs/configuration.md index edbea9c803..ff720a5d8e 100644 --- a/crates/ty/docs/configuration.md +++ b/crates/ty/docs/configuration.md @@ -18,9 +18,9 @@ Valid severities are: **Type**: `dict[RuleName, "ignore" | "warn" | "error"]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.rules] possibly-unresolved-reference = "warn" division-by-zero = "ignore" @@ -45,9 +45,9 @@ configuration setting. **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] extra-paths = ["./shared/my-search-path"] ``` @@ -76,9 +76,9 @@ This option can be used to point to virtual or system Python environments. **Type**: `str` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] python = "./custom-venv-location/.venv" ``` @@ -103,9 +103,9 @@ If no platform is specified, ty will use the current platform: **Type**: `"win32" | "darwin" | "android" | "ios" | "linux" | "all" | str` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] # Tailor type stubs and conditionalized type definitions to windows. python-platform = "win32" @@ -137,9 +137,9 @@ to reflect the differing contents of the standard library across Python versions **Type**: `"3.7" | "3.8" | "3.9" | "3.10" | "3.11" | "3.12" | "3.13" | "3.14" | .` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] python-version = "3.12" ``` @@ -165,9 +165,9 @@ it will also be included in the first party search path. **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] # Multiple directories (priority order) root = ["./src", "./lib", "./vendor"] @@ -185,9 +185,9 @@ bundled as a zip file in the binary **Type**: `str` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.environment] typeshed = "/path/to/custom/typeshed" ``` @@ -240,9 +240,9 @@ If not specified, defaults to `[]` (excludes no files). **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [[tool.ty.overrides]] exclude = [ "generated", @@ -268,9 +268,9 @@ If not specified, defaults to `["**"]` (matches all files). **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [[tool.ty.overrides]] include = [ "src", @@ -292,9 +292,9 @@ severity levels or disable them entirely. **Type**: `dict[RuleName, "ignore" | "warn" | "error"]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [[tool.ty.overrides]] include = ["src"] @@ -358,9 +358,9 @@ to re-include `dist` use `exclude = ["!dist"]` **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.src] exclude = [ "generated", @@ -399,9 +399,9 @@ matches `/src` and not `/test/src`). **Type**: `list[str]` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.src] include = [ "src", @@ -421,9 +421,9 @@ Enabled by default. **Type**: `bool` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.src] respect-ignore-files = false ``` @@ -450,9 +450,9 @@ it will also be included in the first party search path. **Type**: `str` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.src] root = "./app" ``` @@ -471,9 +471,9 @@ Defaults to `false`. **Type**: `bool` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.terminal] # Error if ty emits any warning-level diagnostics. error-on-warning = true @@ -491,9 +491,9 @@ Defaults to `full`. **Type**: `full | concise` -**Example usage** (`pyproject.toml`): +**Example usage**: -```toml +```toml title="pyproject.toml" [tool.ty.terminal] output-format = "concise" ```