doc warden是由azure sdk团队创建的一个内部项目。ci构建将使用它来确保满足文档标准。有关详细信息，请参阅自述文件。
doc-warden的Python项目详细描述
Doc Warden
azure sdk团队拥有的每个ci构建还需要验证目标repo中的文档是否符合一组标准。doc warden旨在简化这些检查在ci构建中的实现。
功能：
- 执行自述标准
- 出现自述文件
- 自述文件有适当的内容
- 为包含的观察包生成报告
此软件包在Python2.7->；3.8上测试。
先决条件
此包将作为azure devops中管道的一部分运行。因此，如果在尝试安装或使用doc warden.之前，如果pip是一个无法识别的命令，则必须先安装python。o installwarden，在完成python安装之后运行以下命令
此外，典狱长使用设置工具和控制盘分发，因此这些软件包也应在安装前提供。
/:> python -m ensurepip
/:> pip install setuptools wheel
用法
现在，典狱长支持两个主要目的。自述执行（扫描，内容，显示）和包索引（索引）。
示例用法（对于以上任何命令）：
<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
参数选项
命令
目前支持3个命令。值：['scan'，'presence'，'content'，索引]必需。
扫描- 在目标目录上同时运行
content和presence强制。
- 在目标目录上同时运行
内容- 仅在目标目录上运行
contentreadme enforcement。确保每个文件中的内容与.docsettings文件中定义的正则表达式模式匹配。
- 仅在目标目录上运行
状态- 仅在目标目录上运行
presencereadme enforcement。确保readme存在于它们应该存在的地方。
- 仅在目标目录上运行
索引- 清点目标文件夹。尝试利用选定的docsettings来发现目录中的所有包，并生成
packages.md索引文件。
- 清点目标文件夹。尝试利用选定的docsettings来发现目录中的所有包，并生成
--扫描目录
目标目录典狱长应该正在扫描。必需。
--扫描语言
典狱长按照惯例检查包裹，所以它需要理解它所看的是什么语言。必须在.docsettings文件中或通过参数填充。必需。
--配置位置
默认情况下，管理员在存储库的根目录中查找.docsettings文件。但是，填充此位置将覆盖此行为，而不是从此参数中的位置提取文件。可选。
--包输出
重写在执行index命令期间将生成的packages.md文件拖放到的默认位置。
--详细输出< /代码>
启用或禁用HTML报表的输出。默认为false。可选。
DevOps使用注意事项
-d参数应该是$（build.sourcesdirectory）。这将指向与ci相关联的回购协议。
方法论
强制显示自述文件
我们什么时候应该有自述文件？
始终：
- 在回购协议的根处
- 与
包目录关联
.net
包目录由：
sdk目录下的一个*，csproj文件- 注意，这只是一个代理。
管理员试图按惯例省略测试项目。
- 注意，这只是一个代理。
巨蟒
包目录由：
- 存在
setup.py文件
Java
包目录由：
- 存在
pom.xml文件- 内的pom
<；packaging>；值设置为jar
- 内的pom
节点&js
包目录由：
- 存在
package.json文件
执行自述内容
文档管理员可以检查发现的自述文件，以确保存在一组配置的节。它是如何工作的？文档管理员将确保必读部分中定义的每个正则表达式与自述文件中的至少一个部分头匹配。如果所有模式至少匹配一个标题，自述文件将通过内容验证。
其他注意事项：
节头是任何将导致<；h1>；到<；h2>；HTML标记的标记或RST。典狱长将对目标回购协议中省略路径之外的readme.rst或readme.md文件进行内容验证。
控件、.docsettings.yml文件和您
特殊情况通常需要配置。似乎合乎逻辑的是，需要一个中心位置（每个回购）来覆盖常规设置。为此，将在每个repo中添加一个新的.docsettings.yml文件。
<repo-root>
│ README.md
│ .docsettings.yml
│
└───.azure-pipelines
│ │ <build def>
│
└───<other files and folders>
此文件的存在允许每个存储库自定义在其存储库中执行的方式。
Java回购的示例文档设置文件
omitted_paths:
- archive/*
language: java
root_check_enabled: True
required_readme_sections:
- "(Client Library for Azure .*|Microsoft Azure SDK for .*)"
- Getting Started
known_presence_issues:
- ['cognitiveservices/data-plane/language/bingspellcheck', '#2847']
known_content_issues:
- ['sdk/template/azure-sdk-template/README.md','#1368']
上面的配置告诉典狱长…
- 回购协议中的语言是
java - 以确保存储库的根目录中存在a
readme.md。 - 从自述文件检查中省略
archive/下的任何路径。
现在语言的可能值是['net'，'java'，'js'，'python']。当前不支持超过一种目标语言。
必读部分配置
本节指示管理员验证在任何发现的自述文件中，每个提供的节模式至少有一个匹配的节标题。完全支持regex。
示例.docsettings文件中列出的两项将：
- 匹配由简单正则表达式匹配的头
- 匹配标题为"Getting Started"（开始）的标题
注意，regex被引号包围，regex将在这里中断配置文件的解析。
已知存在问题和已知内容问题配置
Doc Warden设计用于在检测到故障时崩溃生成。然而，绝大多数情况下，这些问题不能立即得到解决。在上述配置中，有两条路径突出显示为已知问题。
第一个，已知存在问题告诉管理员，在指定路径检测到的存在故障应被忽略，并且不应导致崩溃的生成。描述每个已知问题的元组既指定了已知问题是什么，也指定了某种理由。附加issueid的异常是不失败构建的一个很好的理由。
我们知道这个问题，并在下面的github问题中跟踪它。
已知内容问题参数与已知存在问题检查功能相同。如果自述文件被列为"已知"失败，则典狱长不会破坏整个CI版本。
包索引排除列表和包索引遍历停止配置
索引包通常作为夜间（或触发的）自动化的一部分来完成。在这种情况下，有时管理员可能会检测到用户希望从生成的packages.md文件中忽略的包id。azure sdk团队利用
包索引排除列表数组成员以启用这种情况。
包索引遍历停止仅在分析.NET语言回购时使用。这是由于如何为.net项目实现readme和changelog的发现逻辑。具体来说，a.csproj的readme通常是从其父.csproj位置向上的两个目录！
对于.NET，管理员将一次遍历一个目录，在每个遍历目录中查找自述文件和更改日志文件。典狱长将继续穿越，直到…
- 它发现一个文件夹，其中有一个
.sln。 - 它遇到与
包索引遍历停止中的文件夹完全匹配的文件夹
注意，除非设置了遍历停止，否则 sdk for net.docsettings对于排除列表和遍历停止都是一个很好的示例。 如果您遇到任何错误或有任何建议，请在此处提交问题并分配给 欢迎加入QQ群-->： 979659372
warden甚至不会对.net repo执行索引。
提供反馈
scbedd
推荐PyPI第三方库