docs: fix inconsistencies, remove low informative twoslash examples (#…

…6200)

docs/.vitepress/config.ts

@@ -60,7 +60,16 @@ export default ({ mode }: { mode: string }) => {
         light: 'github-light',
         dark: 'github-dark',
       },
-      codeTransformers: mode === 'development' ? [] : [transformerTwoslash()],
+      codeTransformers: mode === 'development'
+        ? []
+        : [transformerTwoslash({
+            processHoverInfo: (info) => {
+              if (info.includes(process.cwd())) {
+                return info.replace(new RegExp(process.cwd(), 'g'), '')
+              }
+              return info
+            },
+          })],
     },
     themeConfig: {
       logo: '/logo.svg',

docs/.vitepress/scripts/cli-generator.ts

@@ -5,10 +5,37 @@ import type { CLIOption, CLIOptions } from '../../../packages/vitest/src/node/cl
 import { cliOptionsConfig } from '../../../packages/vitest/src/node/cli/cli-config'
 
 const docsDir = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
-const cliTablePath = resolve(docsDir, './guide/cli-table.md')
+const cliTablePath = resolve(docsDir, './guide/cli-generated.md')
 
 const nonNullable = <T>(value: T): value is NonNullable<T> => value !== null && value !== undefined
 
+const skipCli = new Set([
+  'mergeReports',
+  'changed',
+  'shard',
+])
+
+const skipConfig = new Set([
+  'config',
+  'api.port',
+  'api.host',
+  'api.strictPort',
+  'coverage.watermarks.statements',
+  'coverage.watermarks.lines',
+  'coverage.watermarks.branches',
+  'coverage.watermarks.functions',
+  'coverage.thresholds.statements',
+  'coverage.thresholds.branches',
+  'coverage.thresholds.functions',
+  'coverage.thresholds.lines',
+  'standalone',
+  'clearScreen',
+  'color',
+  'run',
+  'hideSkippedTests',
+  'dom',
+])
+
 function resolveOptions(options: CLIOptions<any>, parentName?: string) {
   return Object.entries(options).flatMap(
     ([subcommandName, subcommandConfig]) => resolveCommand(
@@ -19,7 +46,7 @@ function resolveOptions(options: CLIOptions<any>, parentName?: string) {
 }
 
 function resolveCommand(name: string, config: CLIOption<any> | null): any {
-  if (!config) {
+  if (!config || skipCli.has(name)) {
     return null
   }
 
@@ -37,17 +64,19 @@ function resolveCommand(name: string, config: CLIOption<any> | null): any {
   }
 
   return {
-    title,
+    title: name,
+    cli: title,
     description: config.description,
   }
 }
 
 const options = resolveOptions(cliOptionsConfig)
 
-const template = `
-| Options       |               |
-| ------------- | ------------- |
-${options.map(({ title, description }) => `| ${title} | ${description} |`).join('\n')}
-`.trimStart()
+const template = options.map((option) => {
+  const title = option.title
+  const cli = option.cli
+  const config = skipConfig.has(title) ? '' : `[${title}](/config/#${title.toLowerCase().replace(/\./g, '-')})`
+  return `### ${title}\n\n- **CLI:** ${cli}\n${config ? `- **Config:** ${config}\n` : ''}\n${option.description}\n`
+}).join('\n')
 
 writeFileSync(cliTablePath, template, 'utf-8')

docs/advanced/api.md

@@ -8,7 +8,7 @@ Vitest exposes experimental private API. Breaking changes might not follow SemVe
 
 You can start running Vitest tests using its Node API:
 
-```js twoslash
+```js
 import { startVitest } from 'vitest/node'
 
 const vitest = await startVitest('test')
@@ -38,7 +38,7 @@ Alternatively, you can pass in the complete Vite config as the fourth argument,
 
 You can create Vitest instance yourself using `createVitest` function. It returns the same `Vitest` instance as `startVitest`, but it doesn't start tests and doesn't validate installed packages.
 
-```js twoslash
+```js
 import { createVitest } from 'vitest/node'
 
 const vitest = await createVitest('test', {
@@ -50,7 +50,7 @@ const vitest = await createVitest('test', {
 
 You can use this method to parse CLI arguments. It accepts a string (where arguments are split by a single space) or a strings array of CLI arguments in the same format that Vitest CLI uses. It returns a filter and `options` that you can later pass down to `createVitest` or `startVitest` methods.
 
-```ts twoslash
+```ts
 import { parseCLI } from 'vitest/node'
 
 parseCLI('vitest ./files.ts --coverage --browser=chrome')

docs/advanced/pool.md

@@ -14,9 +14,9 @@ Vitest runs tests in pools. By default, there are several pools:
 
 You can provide your own pool by specifying a file path:
 
-```ts twoslash
+```ts
 import { defineConfig } from 'vitest/config'
-// ---cut---
+
 export default defineConfig({
   test: {
     // will run every file with a custom pool by default

docs/advanced/reporters.md

@@ -6,7 +6,7 @@ You can import reporters from `vitest/reporters` and extend them to create your
 
 In general, you don't need to create your reporter from scratch. `vitest` comes with several default reporting programs that you can extend.
 
-```ts twoslash
+```ts
 import { DefaultReporter } from 'vitest/reporters'
 
 export default class MyDefaultReporter extends DefaultReporter {

docs/advanced/runner.md

@@ -110,7 +110,7 @@ Snapshot support and some other features depend on the runner. If you don't want
 
 You can extend Vitest task system with your tasks. A task is an object that is part of a suite. It is automatically added to the current suite with a `suite.task` method:
 
-```js twoslash
+```js
 // ./utils/custom.js
 import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite'
 
@@ -134,7 +134,7 @@ export const myCustomTask = createTaskCollector(
 )
 ```
 
-```js twoslash
+```js
 // ./garden/tasks.test.js
 import { afterAll, beforeAll, describe, myCustomTask } from '../custom.js'
 import { gardener } from './gardener.js'