Doc Warden

Azure-SDK 团队拥有的每个 CI 构建（持续集成）都需要验证目标仓库中的文档是否满足一系列标准。《Doc-warden》旨在简化 CI 构建中这些检查的实现。

功能

• 强制执行README标准
  • 存在README
  • README包含适当的内容
• 强制执行变更日志标准
  • 存在变更日志
  • 变更日志包含最新软件包版本的条目和内容
• 为包含的观察到的软件包生成报告

此软件包在Python 3.4 -> 3.8上进行了测试。自0.7.0版本开始，此软件包仅支持python3。

先决条件

本软件包旨在作为Azure DevOps管道的一部分运行。因此，在尝试安装或使用Doc-Warden之前，必须先安装Python。虽然大多数现代Python安装都预装了pip，但如果在尝试安装warden时pip不是一个可识别的命令，请在Python安装完成后运行以下命令。

此外，warden使用setuptools和wheel进行分发，因此在安装之前也应存在这些包。

/:> python -m ensurepip
/:> pip install setuptools wheel

用法

目前，warden支持两个主要功能。1. 读取说明和变更日志强制执行（scan、content、presence），2. 软件包索引（index）。

示例用法（适用于上述任何命令）

<pre-step, clone target repository>
...
/:> pip install setuptools wheel
/:> pip install doc-warden
...
<next task, because PATH doesn't update without another one>
/:> ward scan -d $(Build.SourcesDirectory)

关于上述示例的说明

• 假设.docsettings文件位于存储库的根目录。

若要提供不同的路径（例如，azure-sdk-for-java所做的那样...），请使用

/:> ward scan -d $(Build.SourcesDirectory) -c $(Build.SourcesDirectory)/eng/.docsettings.yml

参数选项

command目前支持3个命令。值：['scan', 'presence', 'content', index] 必需。

• scan
  • 在目标目录上运行content和presence强制执行。
• content
  • 仅在目标目录上运行content强制执行。确保
    • 每个说明中的内容与.docsettings文件中定义的正则表达式模式匹配
    • 每个变更日志都包含最新版本的条目。
• presence
  • 仅在目标目录上运行presence强制执行。确保说明和变更日志存在于它们应该存在的地方。
• index
  • 对目标文件夹进行盘点。尝试利用选择的docsettings发现目录中的所有包，并生成packages.md索引文件。

--scan-directory warden应扫描的目标目录。必需。

--repo-root 存储库的根目录。配置文件中的条目应相对于此目录。 可选。

--scan-language warden通过约定检查包，因此它需要了解它正在查看什么语言。这必须在.docsettings文件或通过参数中设置。 可选。

--config-location 默认情况下，warden在存储库的根目录中查找.docsettings文件。但是，填充此位置将覆盖此行为，并从此参数指定的位置拉取文件。 可选。

--pipeline-stage 管道的阶段。可以是pr、ci或release。 可选。

--target 指定要运行强制执行的文件，例如readme或changelog。仅在运行content或presence验证时使用。 可选。

--package-output 覆盖执行index命令期间生成的packages.md文件默认位置。

--verbose-output 启用或禁用HTML报告的输出。默认为false。 可选。

关于Devops使用的说明

应将-d参数设置为$(Build.SourcesDirectory)。这将使warden指向已与CI关联的存储库。

方法

强制执行读取说明存在

我们何时期望读取说明和/或变更日志存在？

总是

• 在存储库的根目录（仅读取说明）
• 与package目录相关联（读取说明和变更日志）

.Net

包目录由以下内容表示

• 在sdk目录下的一个*,csproj文件
  • 注意，这只是一个代理。 warden通过约定尝试省略测试项目。

Python

包目录由以下内容表示

• 存在一个setup.py文件

Java

包目录由以下内容表示

• 存在一个 pom.xml 文件
  • POM 中的 <packaging> 值设置为 JAR

Node & JS

包目录由以下内容表示

• 存在一个 package.json 文件

强制执行 Readme 内容

doc-warden 能够检查发现的 Readme 文件，以确保配置的某些部分存在。它是如何工作的？doc-warden 会确保在 required_readme_sections 中定义的每个正则表达式至少匹配 Readme 中的一个部分标题。如果所有模式都至少匹配一个标题，则 Readme 将通过内容验证。

其他注意事项

• section 标题是任何会生成 <h1> 到 <h2> HTML 标签的 markdown 或 RST。
• warden 将验证目标仓库中 omitted_paths 外找到的任何 readme.rst 或 readme.md 文件的内容。

强制执行 Changelog 内容

doc-warden 检查 changelog 文件中的最新条目，以确保它匹配软件包的最新版本。它还检查条目是否为空。

控制，.docsettings.yml 文件，以及您

通常需要配置特殊情况。似乎有必要有一个中央位置（每个仓库）来覆盖传统设置。为此，将为每个仓库添加一个新的 .docsettings.yml 文件。

<repo-root>
│   README.md
│   .docsettings.yml
│
└───.azure-pipelines
│   │   <build def>
│   
└───<other files and folders>

此文件的存在允许每个仓库自定义其仓库内强制执行的执行方式。

Java 仓库的示例 DocSettings 文件

omitted_paths:
  - archive/*
  - sdk/eventhub/
language: java
root_check_enabled: True
required_readme_sections:
  - "(Client Library for Azure .*|Microsoft Azure SDK for .*)"
  - Getting Started
    - Install Package
    - Prerequisites
    - Authenticate the Client
known_presence_issues:
  - ['cognitiveservices/data-plane/language/bingspellcheck/README.md', '#2847']
  - ['cognitiveservices/data-plane/language/bingspellcheck/CHANGELOG.md', '#2847']
known_content_issues:
  - ['sdk/template/azure-sdk-template/README.md','#1368']
  - ['sdk/template/azure-sdk-template/CHANGELOG.md','#1368']

上述配置告诉 warden...

• 仓库中的语言是 java
• 确保在仓库根目录中存在 README.md。
• 排除 archive/ 下的任何路径的 Readme 检查。
• 排除 sdk/eventhub/ 下直接找到的路径。
  • 这意味着如果 sdk/eventhub/azure-messaging/ 下存在 Readme 内容问题，它仍然会抛出错误！

当前 language 的可能值是 ['net', 'java', 'js', 'python']。目前不支持超过一个目标语言。

required_readme_sections 配置

本节指示 warden 验证在任何发现的 Readme 中至少有一个与提供的 section 模式匹配的标题。请注意，支持 嵌套 规范。正则表达式完全支持。

从示例 .docsettings 文件中列出的两个项目将

• 匹配由简单正则表达式表达式匹配的标题
• 匹配标题为 "入门" 的标题 - 在 "入门" 标题下验证是否存在 3 个附加标题。- doc-warden 将搜索到下一个同等重要性的标题的下一个标题。 - 这意味着在搜索 # 入门 标题下时，doc-warden 将扫描到下一个 H1 标题。

请注意，正则表达式被引号包围，这将中断配置文件的 yml 解析。

known_presence_issues 和 known_content_issues 配置

doc-warden 设计为在检测到失败时崩溃构建。然而，大多数情况下，这些问题无法立即修复。在上面的配置中，有两个路径被标记为已知问题。

第一个，known_presence_issues，告诉 warden 在指定路径上检测到的存在失败应该被忽略，并且不应导致构建崩溃。每个已知问题的 tuple 描述了已知问题是什么，以及某种形式的理由。带有 issueId 的异常是一个很好的理由，不应使构建失败。

我们已经注意到这个问题，并且在以下 github 问题上进行了跟踪。

known_content_issues 参数与 known_presence_issues 检查功能完全相同。如果说明文件被列为“已知存在失败”，则整个 CI 构建不会被 Warden 终止。

package_indexing_exclusion_list 和 package_indexing_traversal_stops 配置

通常将包索引作为夜间（或触发）自动化的一部分执行。在这种情况下，有时 warden 可能会检测到用户希望从生成的 packages.md 文件中排除的 PackageId。Azure SDK 团队利用 package_indexing_exclusion_list 数组成员来实现这种类型的场景。

package_indexing_traversal_stops 仅在解析 .NET 语言仓库时使用。这是由于 .NET 项目的说明和变更日志发现逻辑的实现方式。具体来说，.csproj 的说明通常在其父 .csproj 位置的上一个目录中！

对于 .net，warden 会逐个目录向上遍历，在每个遍历的目录中查找说明和变更日志文件。 warden 将继续遍历，直到...

1. 发现一个包含 .sln 文件的文件夹
2. 遇到一个与 package_indexing_traversal_stops 中存在的文件夹完全匹配的文件夹

请注意，warden 除非设置了遍历停止，否则甚至不会对 .NET 仓库执行索引。

net SDK .docsettings 是关于排除列表以及遍历停止的一个很好的例子。

提供反馈

如果您遇到任何错误或有任何建议，请在此处提交问题 here 并分配给 scbedd。