oskarstark/doctor-rst

DOCtor-RST Docker镜像文档

概述与主要用途

DOCtor-RST 是一款用于根据给定规则检查文档规范性的工具，可集成于 CI/CD 流程或本地环境，通过自动化检查确保文档符合预设标准，提升文档质量与一致性。

核心功能与特性

• 文档规则检查：基于预设规则对 .rst 格式文档进行规范性校验
• 多错误格式化器：支持 GitHub PR 标注、控制台可读输出等多种错误展示方式
• 缓存加速：支持在 GitHub Actions 中配置缓存，提升重复构建效率
• 自定义文档路径：可指定非根目录的文档存放路径
• 环境自适应：默认根据运行环境（如 GitHub Actions）自动选择合适的错误格式化器

使用场景与适用范围

• GitHub 项目文档质量控制：在代码提交、Pull Request (PR) 等环节自动触发文档检查，实时反馈问题
• 本地文档开发辅助：文档编写过程中本地运行检查，即时修正不规范内容
• 大型文档项目管理：通过规则校验统一团队文档风格与格式

使用方法与配置说明

GitHub Actions 集成

基础配置示例

在 GitHub 仓库的 .github/workflows/ 目录下创建 lint 工作流文件（如 lint.yaml）：

yaml
# .github/workflows/lint.yaml
name: Lint

on:
    push:
    pull_request:

jobs:
    doctor-rst:
        name: DOCtor-RST
        runs-on: ubuntu-latest
        steps:
            - name: "Checkout code"
              uses: actions/checkout@v2

            - name: DOCtor-RST
              uses: docker://oskarstark/doctor-rst
              with:
                  args: --short --error-format=github

自定义文档目录

若 .rst 文件未存放在项目根目录，通过 DOCS_DIR 环境变量指定路径：

diff
              uses: docker://oskarstark/doctor-rst
              with:
                  args: --short --error-format=github
+              env:
+                  DOCS_DIR: 'docs/'  # 文档存放目录，如 'docs/source/'

配置缓存加速构建

通过缓存机制减少重复依赖下载，提升 GitHub Actions 运行效率：

diff
        steps:
            - name: "Checkout code"
              uses: actions/checkout@v2

+            - name: "Create cache directory"
+              run: mkdir .cache
+
+            - name: "Extract base branch name"
+              run: echo "##[set-output name=branch;]$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})"
+              id: extract_base_branch
+
+            - name: "Cache DOCtor-RST"
+              uses: actions/cache@v2
+              with:
+                  path: .cache
+                  key: doctor-rst-${{ runner.os }}-${{ steps.extract_base_branch.outputs.branch }}
+                  restore-keys: |
+                      doctor-rst-${{ runner.os }}-
+                      doctor-rst-   
+
            - name: "Run DOCtor-RST"
              uses: docker://oskarstark/doctor-rst
              with:
-                 args: --short --error-format=github
+                 args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache

Docker 本地运行

基本命令

直接通过 Docker 运行镜像，检查本地文档：

bash
docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst:latest

• --rm：容器退出后自动删除
• -it：交互式终端
• -e DOCS_DIR='/docs'：指定容器内文档目录（需与挂载路径对应）
• -v ${PWD}:/docs：将当前目录挂载到容器内 /docs 路径

本地命令行使用

若已获取源码，可直接通过本地命令运行：

bash
# 检查 dummy 文档，使用 @Symfony 规则组
bin/doctor-rst analyze dummy --group=@Symfony

# 检查 dummy 文档，使用 @Sonata 规则组
bin/doctor-rst analyze dummy --group=@Sonata

配置参数说明

错误格式化器

控制错误输出格式，支持以下类型：

使用方法

通过 --error-format 参数强制指定格式化器：

bash
# 在 GitHub Actions 中强制使用控制台输出
args: --short --error-format=console

其他常用参数

可用规则

完整规则列表请参见 官方规则文档（需访问项目源码获取）。

待办事项

• 支持注册自定义规则
• 将逻辑从命令迁移至服务层