[site] add a few titles to TOML code blocks

Fixes #1765.

site/src/docs/ci-features/archiving.md

@@ -59,7 +59,7 @@ build process creates artifacts outside of Cargo that are required for Rust test
 
 Use the `profile.<profile-name>.archive.include` configuration option for this. For example:
 
-```toml
+```toml title="Extra archive files in <code>.config/nextest.toml</code>"
 [profile.default]
 archive.include = [
     { path = "my-extra-path", relative-to = "target" },

site/src/docs/configuration/index.md

@@ -16,7 +16,7 @@ cargo-nextest supports multiple _profiles_, where each profile is a set of optio
 
 Here is a recommended profile for CI runs:
 
-```toml
+```toml title="Configuring a CI profile in <code>.config/nextest.toml</code>"
 [profile.ci]
 # Print out output for failing tests as soon as they fail, and also at the end
 # of the run (for easy scrollability).

site/src/docs/configuration/minimum-versions.md

@@ -19,21 +19,21 @@ field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-
 To set a minimum required version, add to [`.config/nextest.toml`](index.md), at the top of
 the file:
 
-```toml
+```toml title="Minimum required version in <code>.config/nextest.toml</code>"
 nextest-version = "0.9.55"
 # or
 nextest-version = { required = "0.9.55" }
 ```
 
 To set a minimum recommended version, add to `.config/nextest.toml`:
 
-```toml
+```toml title="Minimum recommended version"
 nextest-version = { recommended = "0.9.55" }
 ```
 
 Both required and recommended versions can be set simultaneously:
 
-```toml
+```toml title="Minimum required and recommended versions"
 nextest-version = { required = "0.9.53", recommended = "0.9.55" }
 ```
 

site/src/docs/configuration/per-test-overrides.md

@@ -43,7 +43,7 @@ At least one of these fields must be specified:
 
 ## Example
 
-```toml
+```toml title="Basic example for per-test settings in <code>.config/nextest.toml</code>"
 [profile.ci]
 retries = 1
 
@@ -81,7 +81,7 @@ Precedence is evaluated separately for each override. If a particular override d
 
 ### Example
 
-```toml
+```toml title="Example for per-test settings in <code>.config/nextest.toml</code>"
 [profile.default]
 retries = 0  # this is the default, so it doesn't need to be specified
 slow-timeout = "30s"

site/src/docs/configuration/setup-scripts.md

@@ -21,7 +21,7 @@ Setup scripts are configured in two parts: _defining scripts_, and _setting up r
 
 Setup scripts are defined using the top-level `script` configuration. For example, to define a script named "my-script", which runs `my-script.sh`:
 
-```toml
+```toml title="Setup script definition in <code>.config/nextest.toml</code>"
 [script.my-script]
 command = 'my-script.sh'
 ```
@@ -45,7 +45,7 @@ Setup scripts can have the following configuration options attached to them:
 
 ### Example
 
-```toml
+```toml title="Advanced setup script definition"
 [script.db-generate]
 command = 'cargo run -p db-generate'
 slow-timeout = { period = "60s", terminate-after = 2 }
@@ -58,7 +58,7 @@ capture-stderr = false
 
 In configuration, you can create rules for when to use scripts on a per-profile basis. This is done via the `profile.<profile-name>.scripts` array. For example, you can set up a script that generates a database if tests from the `db-tests` package, or any packages that depend on it, are run.
 
-```toml
+```toml title="Basic rules"
 [[profile.default.scripts]]
 filter = 'rdeps(db-tests)'
 setup = 'db-generate'
@@ -68,15 +68,15 @@ setup = 'db-generate'
 
 Setup scripts can also filter based on platform, using the rules listed in [_Specifying platforms_](../configuration/specifying-platforms.md):
 
-```toml
+```toml title="Platform-specific rules"
 [[profile.default.scripts]]
 platform = { host = "cfg(unix)" }
 setup = 'script1'
 ```
 
 A set of scripts can also be specified. All scripts in the set will be executed.
 
-```toml
+```toml title="Multiple setup scripts"
 [[profile.default.scripts]]
 filter = 'test(/^script_tests::/)'
 setup = ['script1', 'script2']

site/src/docs/configuration/specifying-platforms.md

@@ -8,7 +8,7 @@ icon: material/laptop
 
 For example, with the following configuration:
 
-```toml
+```toml title="Platform overrides in <code>.config/nextest.toml</code>"
 [[profile.default.overrides]]
 platform = 'cfg(target_os = "linux")'
 retries = 3
@@ -22,7 +22,7 @@ While cross-compiling code, nextest's per-test overrides support filtering by ei
 
 If `platform` is set to a string, then nextest will consider it to be the _target_ filter. For example, if the following is specified:
 
-```toml
+```toml title
 [[profile.default.overrides]]
 platform = 'aarch64-apple-darwin'
 slow-timeout = "120s"
@@ -38,7 +38,7 @@ In addition to a plain string, `platform` can also be set to a map with `host` a
 
 For example:
 
-```toml
+```toml title="Cross-compile overrides"
 [[profile.default.overrides]]
 platform = { host = 'cfg(target_os = "macos")' }
 retries = 1

site/src/docs/configuration/test-groups.md

@@ -44,7 +44,7 @@ Test groups are specified in [nextest's configuration](index.md) by:
 
 For example:
 
-```toml
+```toml title="Test groups in <code>.config/nextest.toml</code>"
 [test-groups]
 resource-limited = { max-threads = 4 }
 serial-integration = { max-threads = 1 }

site/src/docs/configuration/threads-required.md

@@ -10,7 +10,7 @@ With nextest, you can mark heavy tests as taking up multiple threads or "slots"
 
 For example, on a machine with 16 logical CPUs, nextest will run 16 tests concurrently by default. However, if you mark tests that begin with `tests::heavy::` as requiring 2 threads each:
 
-```toml
+```toml title="Heavy tests in <code>.config/nextest.toml</code>"
 [[profile.default.overrides]]
 filter = 'test(/^tests::heavy::/)'
 threads-required = 2

site/src/docs/features/retries.md

@@ -43,7 +43,7 @@ In those cases, you can insert delays between test attempts with a backoff algor
 
 To insert a constant delay between test attempts, use the fixed backoff algorithm. For example, to retry tests up to twice with a 1 second delay between attempts, use:
 
-```toml
+```toml title="Fixed backoff in <code>.config/nextest.toml</code>"
 [profile.default]
 retries = { backoff = "fixed", count = 2, delay = "1s" }
 ```
@@ -52,14 +52,14 @@ retries = { backoff = "fixed", count = 2, delay = "1s" }
 
 Nextest also supports [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff), where the delay between attempts doubles each time. For example, to retry tests up to 3 times with successive delays of 5 seconds, 10 seconds, and 20 seconds, use:
 
-```toml
+```toml title="Exponential backoff"
 [profile.default]
 retries = { backoff = "exponential", count = 3, delay = "5s" }
 ```
 
 A maximum delay can also be specified to avoid delays from becoming too large. In the above example, if `count = 5`, the fourth and fifth retries would be with delays of 40 seconds and 80 seconds, respectively. To clamp delays at 30 seconds, use:
 
-```toml
+```toml title="Exponential backoff with a maximum delay"
 [profile.default]
 retries = { backoff = "exponential", count = 3, delay = "5s", max-delay = "30s" }
 ```
@@ -70,7 +70,7 @@ This effectively performs a [truncated exponential backoff](https://en.wikipedia
 
 To avoid [thundering herd problems](https://en.wikipedia.org/wiki/Thundering_herd_problem), it can be useful to add randomness to delays. To do so, use `jitter = true`.
 
-```toml
+```toml title="Exponential backoff with jitter"
 [profile.default]
 retries = { backoff = "exponential", count = 3, delay = "1s", jitter = true }
 ```
@@ -79,19 +79,19 @@ retries = { backoff = "exponential", count = 3, delay = "1s", jitter = true }
 
 The current jitter algorithm picks a value in between `0.5 * delay` and `delay` uniformly at random. This is not part of the stable interface and is subject to change.
 
-## Per-test overrides
+## Per-test settings
 
-Nextest supports [per-test overrides](../configuration/per-test-overrides.md) for retries, letting you mark a subset of tests as needing retries. For example, to mark test names containing `"test_e2e"` as requiring retries:
+Nextest supports [per-test settings](../configuration/per-test-overrides.md) for retries, letting you mark a subset of tests as needing retries. For example, to mark test names containing `"test_e2e"` as requiring retries:
 
-```toml
+```toml title="Per-test retry configuration"
 [[profile.default.overrides]]
 filter = 'test(test_e2e)'
 retries = 2
 ```
 
 Per-test overrides support the full set of delay and backoff options as well. For example:
 
-```toml
+```toml title="Per-test exponential backoff"
 [[profile.default.overrides]]
 filter = 'test(test_remote_api)'
 retries = { backoff = "exponential", count = 2, delay = "5s", jitter = true }

site/src/docs/features/slow-tests.md

@@ -26,7 +26,7 @@ For tests that take more than a certain amount of time (by default 60 seconds),
 
 To customize how long it takes before a test is marked slow, use the `slow-timeout` [configuration parameter](../configuration/index.md). For example, to set a timeout of 2 minutes before a test is marked slow, add this to `.config/nextest.toml`:
 
-```toml
+```toml title="Slow tests in <code>.config/nextest.toml</code>"
 [profile.default]
 slow-timeout = "2m"
 ```
@@ -37,7 +37,7 @@ Nextest uses the `humantime` parser: see [its documentation](https://docs.rs/hum
 
 Nextest lets you optionally specify a number of `slow-timeout` periods after which a test is terminated. For example, to configure a slow timeout of 30 seconds and for tests to be terminated after 120 seconds (4 periods of 30 seconds), add this to `.config/nextest.toml`:
 
-```toml
+```toml title="Slow tests with termination"
 [profile.default]
 slow-timeout = { period = "30s", terminate-after = 4 }
 ```
@@ -68,14 +68,14 @@ On Unix platforms, nextest creates a [process group] for each test. On timing ou
 
 To customize the grace period, use the `slow-timeout.grace-period` configuration setting. For example, with the `ci` profile, to terminate tests after 5 minutes with a grace period of 30 seconds:
 
-```toml
+```toml title="Termination grace period"
 [profile.ci]
 slow-timeout = { period = "60s", terminate-after = 5, grace-period = "30s" }
 ```
 
 To send SIGKILL to a process immediately, without a grace period, set `slow-timeout.grace-period` to zero:
 
-```toml
+```toml title="Termination without a grace period"
 [profile.ci]
 slow-timeout = { period = "60s", terminate-after = 5, grace-period = "0s" }
 ```
@@ -89,13 +89,13 @@ On Windows, nextest terminates the test immediately in a manner akin to SIGKILL.
 [process group]: https://en.wikipedia.org/wiki/Process_group
 [job objects]: https://docs.microsoft.com/en-us/windows/win32/procthread/job-objects
 
-## Per-test overrides
+## Per-test settings
 
-Nextest supports [per-test overrides](../configuration/per-test-overrides.md) for the `slow-timeout` and `terminate-after` settings.
+Nextest supports [per-test settings](../configuration/per-test-overrides.md) for `slow-timeout` and `terminate-after`.
 
 For example, some end-to-end tests might take longer to run and sometimes get stuck. For tests containing the substring `test_e2e`, to configure a slow timeout of 120 seconds, and to terminate tests after 10 minutes:
 
-```toml
+```toml title="Per-test slow timeouts"
 [[profile.default.overrides]]
 filter = 'test(test_e2e)'
 slow-timeout = { period = "120s", terminate-after = 5 }

site/src/docs/features/target-runners.md

@@ -13,9 +13,9 @@ If you're cross-compiling Rust code, you may wish to run tests through a wrapper
 
 If you're on Linux cross-compiling to Windows, you can choose to run tests through [Wine](https://www.winehq.org/).
 
-If you add the following to `.cargo/config.toml:`
+If you add the following to `.cargo/config.toml`:
 
-```toml
+```toml title="Target runner in <code>.cargo/config.toml</code>"
 [target.x86_64-pc-windows-msvc]
 runner = "wine"
 ```

site/src/docs/integrations/cargo-mutants.md

@@ -22,7 +22,7 @@ cargo mutants --test-tool=nextest
 
 If your tree should always be built with nextest, you can configure this in `.cargo/mutants.toml`:
 
-```toml
+```toml title="Configuring nextest in <code>.cargo/mutants.toml</code>"
 test_tool = "nextest"
 ```
 

site/src/docs/integrations/miri.md

@@ -39,7 +39,7 @@ This does not require installing any special toolchain, and will work even if yo
 
 If nextest detects a Miri environment, it uses the `default-miri` profile by default. Add repository-specific Miri configuration to this profile. For example, to [terminate tests](../features/slow-tests.md#terminating-tests-after-a-timeout) after 2 minutes, add this to `.config/nextest.toml`:
 
-```toml
+```toml title="Miri configuration in <code>.config/nextest.toml</code>
 [profile.default-miri]
 slow-timeout = { period = "60s", terminate-after = 2 }
 ```

site/src/docs/machine-readable/junit.md

@@ -8,7 +8,7 @@ Nextest can produce output in the [JUnit/XUnit XML format](https://llg.cubic.org
 
 To enable JUnit support, add this to your [nextest configuration](../configuration/index.md):
 
-```toml
+```toml title="Basic JUnit configuration in <code>.config/nextest.toml</code>
 [profile.ci.junit]  # this can be some other profile, too
 path = "junit.xml"
 ```
@@ -34,11 +34,11 @@ Configuration options supported for JUnit reports, within the `junit` section:
 `store-failure-output`
 : Whether to store output for failing tests in the `<system-out>` and `<system-err>` elements. Defaults to true.
 
-The `store-success-output` and `store-failure-output` configuration can also be configured as [per-test overrides](../configuration/per-test-overrides.md).
+The `store-success-output` and `store-failure-output` configuration can also be configured on a [per-test basis](../configuration/per-test-overrides.md).
 
 ### Example configuration
 
-```toml
+```toml title="Per-test JUnit settings"
 [profile.default.junit]
 path = "junit.xml"
 # These are the default values, specified for clarity.

site/src/docs/running.md

@@ -79,7 +79,7 @@ For example, some tests might need access to special resources not available to
 workstations. To not run tests in the `special-tests` crate by default, but to run them with the
 `ci` profile:
 
-```toml
+```toml title="Default filter configuration in <code>.config/nextest.toml</code>"
 [profile.default]
 default-filter = 'not package(special-tests)'