Vale 文档测试

Vale 是一个用于英语的语法、风格和用词检查工具。Vale 的配置存储在项目根目录下的 .vale.ini 文件中。例如，gitlab 项目的 .vale.ini。

Vale 支持创建 自定义规则 来扩展多种类型的检查，这些规则我们存储在项目的文档目录中。例如，gitlab 项目的 doc/.vale 目录。

此配置也用于构建管道中，其中会强制执行 错误级别规则。

您可以通过以下方式使用 Vale：

• 在命令行上。
• 在代码编辑器中。
• 在 Git hook 中。Vale 只在 Git hook 中报告错误（与 CI/CD 管道相同的配置），不报告建议或警告。

安装 Vale

使用以下任一方式安装 vale：

• 如果使用 asdf，请使用 asdf-vale 插件。在具有 .tool-versions 文件的 GitLab 项目检出中（示例），运行：

  asdf plugin add vale && asdf install vale

• 使用包管理器：

  • macOS 使用 brew，运行：brew install vale。
  • Linux，使用您发行版的包管理器或 已发布的二进制文件。

在编辑器中配置 Vale

在编辑器中使用检查工具比从命令行运行命令更方便。

要在编辑器中配置 Vale，请根据需要安装以下之一：

• Visual Studio Code ChrisChinchilla.vale-vscode 扩展。 您可以配置插件以仅显示部分警报。

• Sublime Text SublimeLinter-vale 包。要让 Vale 建议显示为蓝色而非红色（错误显示的颜色），请将 vale 配置添加到您的 SublimeLinter 配置中：

  "vale": {
    "styles": [{
      "mark_style": "outline",
      "scope": "region.bluish",
      "types": ["suggestion"]
    }]
  }

• Sublime Text 的 LSP 包 LSP-vale-ls。

• Vim ALE 插件。

• JetBrains IDEs - 虽然没有现有插件，但 此问题评论 包含配置外部工具的技巧。

• Emacs Flycheck 扩展。Flycheck 与 Vale 配合使用的最小配置可能如下：

  (flycheck-define-checker vale
    "A checker for prose"
    :command ("vale" "--output" "line" "--no-wrap"
              source)
    :standard-input nil
    :error-patterns
      ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
    :modes (markdown-mode org-mode text-mode)
    :next-checkers ((t . markdown-markdownlint-cli))
  )
  
  (add-to-list 'flycheck-checkers 'vale)

  在此设置中，markdownlint 检查器被设置为已定义的 vale 检查器的"下一个"检查器。 启用此自定义 Vale 检查器可同时提供 Vale 和 markdownlint 的错误检查。

结果类型

Vale 返回三种类型的结果：

• Error - 用于品牌指南、商标指南以及任何导致文档网站内容渲染不正确的问题。
• Warning - 用于通用风格指南规则、原则和最佳实践。
• Suggestion - 用于可能需要重构文档或更新异常列表的技术写作风格偏好。

这些结果类型具有以下属性：

何时添加新的 Vale 规则

为每个风格指南规则添加 Vale 规则很有吸引力。但是，我们应该注意创建和强制执行 Vale 规则所需的工作量，以及它产生的噪音。

通常，请遵循以下指南：

• 如果您添加了 错误级别 Vale 规则，您必须先修复 文档中该问题的现有实例，然后才能添加该规则。

  如果在单个合并请求中需要修复的问题太多，请以 warning 级别添加该规则。然后在后续的合并请求中修复现有问题。 当问题修复后，将规则提升为 error。

• 如果您添加警告级别或建议级别的规则，请考虑：

  • 它在 Vale 输出中会产生多少额外的警告或建议。如果 额外警告的数量很大，该规则可能过于宽泛。

  • 作者可能因为上下文可接受而忽略它的频率。 如果规则过于主观，则无法充分执行，并会创建 不必要的额外警告。

  • 是否适合在 GitLab UI 的合并请求差异中显示。 如果该规则难以在合并请求中直接实现（例如， 它需要页面重构），请将其设置为建议级别，以便仅在本地编辑器中显示。

在何处添加新的 Vale 规则

新的 Vale 规则属于两个类别之一（在 Vale 中称为 styles）。这些 规则存储在项目 .vale.ini 文件中指定的特定样式目录中。例如， gitlab 项目的 .vale.ini。

在哪里添加新规则取决于您提议的规则类型：

• gitlab_base: 适用于任何 GitLab 文档的基本规则。
• gitlab_docs: 仅适用于发布到 https://docs.gitlab.com 的文档。

大多数新规则属于 gitlab_base。

限制运行的测试

您可以在查看文件时设置 Visual Studio Code 仅显示 Vale 警报的子集：

1. 转到 Preferences > Settings > Extensions > Vale。
2. 在 Vale CLI: Min Alert Level 中，选择要在文件中显示的最低警报级别。

要从命令行运行 Vale 时仅显示 Vale 警报的子集，请使用 --minAlertLevel 标志，它接受 error、warning 或 suggestion。根据需要将其与 --config 结合使用以指向项目中的配置文件：

vale --config .vale.ini --minAlertLevel error doc/**/*.md

省略该标志以显示所有警报，包括 suggestion 级别的警报。

一次测试一个规则

要从命令行运行 Vale 时仅测试单个规则，请修改此 命令，将 OutdatedVersions 替换为规则名称：

vale --no-wrap --filter='.Name=="gitlab_base.OutdatedVersions"' doc/**/*.md

禁用 Vale 测试

您可以禁用文档任何部分的特定 Vale 检查规则或所有 Vale 检查规则：

• 要禁用特定规则，请在文本前添加 <!-- vale gitlab_<type>.rulename = NO --> 标签，在文本后添加 <!-- vale gitlab_<type>.rulename = YES --> 标签，将 rulename 替换为 GitLab 样式 目录中某个测试的文件名。
• 要禁用所有 Vale 检查规则，请在文本前添加 <!-- vale off --> 标签，在文本后添加 <!-- vale on --> 标签。

尽可能只排除有问题的规则和行。

忽略语句不适用于具有 raw 作用域的 Vale 规则。有关更多信息，请参阅此 issue。

有关 Vale 作用域规则的更多信息，请参阅 Vale 的文档。

在提交或推送时显示 Vale 警告

默认情况下，Lefthook 中的 Vale 检查只显示错误级别的问题。默认分支 没有 Vale 错误，因此此处列出的任何错误都是由提交到该分支引入的。

要查看 Vale 警告，请设置一个本地环境变量：VALE_WARNINGS=true。

通过以下方式在提交或推送时启用 Vale 警告以改进文档套件：

• 检测您可能通过提交引入的警告。
• 识别页面中已存在的警告，您可以解决这些警告以减少技术债务。

这些警告：

• 不会阻止提交工作。
• 不会导致管道失败。
• 包含文件的所有警告，而不仅仅是提交引入的警告。

要使用 Lefthook 启用 Vale 警告：

• 自动方式，将 VALE_WARNINGS=true 添加到您的 shell 配置中。

• 手动方式，在 lefthook 调用前加上 VALE_WARNINGS=true。例如：

  VALE_WARNINGS=true bundle exec lefthook run pre-commit

您还可以配置您的编辑器以显示 Vale 警告。

解决 Vale 识别的问题

拼写测试

当 Vale 将有效单词标记为拼写错误时，您可以按照以下指南修复它：

大写（首字母缩写）测试

Uppercase.yml 测试检查全大写单词的错误使用。例如，避免使用 This is NOT important 这样的用法。

如果单词必须全部大写，请遵循以下指南：

可读性评分

在 ReadingLevel.yml 中， 我们实现了 the Flesch-Kincaid grade level test 来确定我们文档的可读性。

作为一般指导原则，评分越低，文档的可读性越高。例如，一组更改前评分为 12， 更改后为 9，表示可读性的迭代改进。该评分并非精确科学，但旨在帮助 表明页面的总体复杂程度。

可读性评分基于每句的单词数和每单词的音节数。有关更多信息，请参阅 Vale 文档。

将 Vale 结果导出到文件

要将所有（或过滤后的）Vale 结果导出到文件，请修改此命令：

# 返回 suggestion、warning 和 error 类型结果
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# 仅返回 warning 和 error 结果
find . -name '*.md' | sort | xargs vale --minAlertLevel warning --output line > ../../results.txt

# 仅返回 error 结果
find . -name '*.md' | sort | xargs vale --minAlertLevel error --output line > ../../results.txt

这些结果可用于生成与文档相关的问题以供 Hackathon 使用。

在本地启用自定义规则

Vale 3.0 及更高版本支持使用两个位置存储规则。此更改使您能够 创建和使用自己的自定义规则，以及项目中包含的规则。

要在 macOS 上本地创建和使用自定义规则：

1. 在 Vale 的 Application Support 文件夹中创建一个本地文件：

   touch ~/Library/Application\ Support/vale/.vale.ini

2. 将以下行添加到您刚刚创建的 .vale.ini 文件中：

   [*.md]
   BasedOnStyles = local

3. 如果文件夹 ~/Library/Application Support/vale/styles/local 不存在， 请创建它：

   mkdir ~/Library/Application\ Support/vale/styles/local

4. 将您想要的规则添加到 ~/Library/Application Support/vale/styles/local。

您 local 样式目录中的规则在 Vale 结果中会以 local 而不是 gitlab 为前缀，如下所示：

$ vale --minAlertLevel warning doc/ci/yaml/index.md

 doc/ci/yaml/index.md
    ...[snip]...
 3876:17   warning  Instead of future tense 'will   gitlab.FutureTense
                    be', use present tense.
 3897:26   error    Remove 'documentation'          local.new-rule

✖ 1 error, 5 warnings and 0 suggestions in 1 file.

相关主题

• Vale 中的样式
• 示例样式，包含您可以改编的规则