企业官网建设流程全解析

• 人工智能
• 深度学习
• 计算机视觉
• OCR

docTR（Document Text Recognition）是一个基于深度学习的 OCR 库，覆盖文本检测、文本识别、版面分析与 KIE 等任务。本文面向想要向 docTR 贡献代码的开发者，完整梳理贡献者需要掌握的知识：仓库代码结构、问题与需求反馈渠道、可编辑开发模式安装、提交规范、单元测试、代码质量检查与文档本地构建。读完本文，你将能搭建起与官方 CI 一致的本地开发环境，并理解每个质量门禁背后的实现细节与仓库证据。

仓库代码结构：一次看懂各目录职责

在动手贡献之前，先了解 docTR 的仓库布局。整个仓库由以下核心目录组成，贡献代码时通常只涉及其中一个或几个：

从 pyproject.toml 的[tool.setuptools.packages.find]配置可以看到，api、demo、docs、notebooks、references、scripts、tests均被排除在打包范围之外，只有doctr/是真正随包发布的代码——这印证了doctr目录是贡献的核心区域，而其余目录更多承担演示、训练与验证的辅助角色。

持续集成（CI）：贡献者只需保证测试覆盖

docTR 使用如下集成来维护代码库质量：

• GitHub Workflow：在推送与 PR 时自动运行构建和覆盖率相关作业；
• Codecov：汇总并回报覆盖率结果。

对贡献者而言，CI 的硬性要求只有一条：为你的代码补充合适的单元测试，确保覆盖率达标。

仓库中实际配置的 CI 工作流可以帮你理解这一要求的具体形态。以 .github/workflows/main.yml 为例，测试工作流拆分为两个并行作业：

• pytest-common：运行pytest tests/common/ -rs --cov --cov-report=xml:coverage-common.xml，对应框架无关的通用测试；
• pytest-torch：运行pytest tests/pytorch/ -rs --cov --cov-report=xml:coverage-pt.xml，对应 PyTorch 后端测试。

两个作业都通过共享的 setup action（.github/actions/setup-env/action.yml）完成环境准备，其中有两点值得注意：

1. 在 Linux 上会预先安装 CPU-only 版 PyTorch（pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu），避免拉取 CI 无法使用的多 GB CUDA 版 torch；
2. 通过actions/cache缓存~/.cache/doctr与~/.cache/huggingface下的预训练模型，加速多轮测试。

两个测试作业完成后，codecov-upload作业下载两份 XML 覆盖率报告并上传至 Codecov（main.yml）。这一作业链与 Makefile 中的make test目标在结构上完全对应，因此本地跑make test即可获得与 CI 一致的第一手反馈。

反馈渠道：问题、特性请求与疑问

贡献不只是写代码。在动手之前，先了解如何把有价值的信息传递给维护者：

特性请求与 Bug 报告：无论遇到问题还是产生特性建议，都建议通过仓库的 Issues 反馈。操作步骤是：先检查该话题是否已在某个打开或关闭的 issue中被覆盖；若没有，再新建 issue。新建时尽量使用 issue 模板，并提供足够的信息以便其他贡献者参与。仓库在 .github/ISSUE_TEMPLATE 中提供了三类模板：bug_report.yml（Bug 报告）、feature_request.yml（特性请求）和config.yml（配置）。其中 Bug 报告模板强制要求填写：Bug 描述、可复现的代码片段、完整错误回溯（traceback）以及环境信息——环境信息通过运行scripts/collect_env.py脚本生成，该脚本就在 scripts/collect_env.py 中。

疑问解答：如果只是想知道"如何用 docTR 做某件事"这类使用层面的问题，则优先到仓库的 Discussions 提问。它的定位是 Q&A 论坛，相当于"docTR 专属的 StackOverflow"。

开发模式安装：搭建可编辑的开发环境

在本地开发 docTR，首先需要以可编辑（editable）模式安装全部开发依赖：

python -m pip install --upgrade pip pip install -e '.[dev]' pre-commit install

三步的含义分别是：升级 pip 至最新、以可编辑模式安装包并附带dev额外依赖、注册 pre-commit 钩子。

dev额外依赖在 pyproject.toml 中有完整定义，实际是一组依赖的合集，可拆解为四类：

• PyTorch 运行时：torch>=2.0.0,<3.0.0、torchvision>=0.15.0、onnx>=1.12.0,<3.0.0；
• 额外能力（extras）：weasyprint>=55.0（HTML 导出）、matplotlib>=3.1.0与mplcursors>=0.3（可视化）；
• 测试：pytest-cov>=7.0.0、onnxruntime>=1.11.0、requests>=2.20.0、psutil>=5.9.5、pandas>=2.0.0；
• 质量：ruff>=0.3.0、mypy>=1.0、pre-commit>=3.0.0；
• 文档：sphinx>=3.0.0,!=3.5.0、sphinxemoji、sphinx-copybutton、docutils<0.23、recommonmark、sphinx-markdown-tables、sphinx-tabs、furo主题等。

需要说明的是，docTR 的运行时要求为requires-python = ">=3.11.0,<4"（pyproject.toml），因此在 Python 3.11 及以上版本中开发是前提。

pre-commit install则依据 .pre-commit-config.yaml 在本地 git 钩子中注册一系列提交前检查，包括：

• check-ast、check-yaml、check-toml、check-json：配置文件语法校验；
• check-added-large-files：阻止提交大文件（docs/images/目录除外）；
• end-of-file-fixer、trailing-whitespace：文件尾与行尾空白规范；
• debug-statements：拦截调试断点残留；
• check-merge-conflict：检测未解决的合并冲突标记；
• no-commit-to-branch：禁止直接向main分支提交（--branch main）；
• 以及基于 Ruff 的ruff --fix（自动修复 lint 问题）和ruff-format（统一格式）。

提交规范：文档字符串与提交信息

docTR 对提交有两个明确要求：

• 代码文档字符串：所有 Python 代码都必须提供 docstring，并遵循Google-style风格（可参考 Sphinx Napoleon 扩展的 Google 风格示例），这样后续能顺畅地接入文档自动构建流程。从 pyproject.toml 的 Ruff 配置也能看到，项目开启了 pydocstyle 规则族（D101、D103、D300等），并由 CI 的 ruff 作业强制执行；同时flake8-quotes规定 docstring 使用双引号（docstring-quotes = "double"）。
• 提交信息：遵循Udacity Git 提交信息指南（类型化的<type>(<scope>): <subject>结构，如feat(detection): ...），便于维护清晰的历史。

单元测试：make test与覆盖率门槛

与 CI 工作流保持一致，本地运行同样的单元测试只需：

make test

从 Makefile 可以看到该目标的完整实现：

test: pytest tests/common/ -rs --cov pytest tests/pytorch/ -rs --cov --cov-append coverage report --fail-under=80 --show-missing

它依次执行tests/common/与tests/pytorch/两批测试，并将两次覆盖率累加，最后要求总覆盖率不低于 80%（--fail-under=80），否则视为失败。这正是 CI 中codecov-upload的本地等价物。此外，Makefile 还提供了分开运行的入口：make test-common只跑通用测试，make test-torch只跑 PyTorch 测试。

对于新增功能，你需要补充对应模块的测试文件。测试体系的质量可以从 tests/conftest.py 中一窥端倪——这里定义了覆盖检测、识别、版面、表格、KIE 等任务的各类 fixture：

• mock_vocab、mock_pdf、mock_image_path、mock_image_folder等基础数据 fixture；
• 各类数据集标注 fixture，如mock_ic13、mock_svt、mock_synthtext_dataset、mock_cord_dataset、mock_funsd_dataset、mock_wildreceipt_dataset等，它们将真实数据集的标注格式（XML、JSON、MAT 等）以最小化样本复现，保证测试无需下载完整数据集；
• 还有mock_detection_label、mock_recognition_label、mock_layout_label、mock_table_label等标注格式 fixture。

这些 fixture 是编写新测试时可复用的现成资产——在新增数据集支持或新模型时，参照对应测试文件（如 tests/common/test_models_detection.py、tests/pytorch/test_models_detection_pt.py）的模式即可快速接入。

代码质量：make quality与make style

docTR 提供两个互补的质量入口：

一次性运行全部质量检查：

make quality

对应的实现（Makefile）：

quality: ruff check . mypy doctr/

即用ruff做 lint 静态检查、用mypy对doctr/包做类型检查。mypy 的严格配置在 pyproject.toml 中：开启了warn_unused_ignores、warn_redundant_casts、no_implicit_optional、check_untyped_defs、implicit_reexport = false等选项，并对第三方库（torchvision、onnxruntime、cv2等）忽略缺失的导入存根。CI 中对应的作业在 .github/workflows/style.yml 中：ruff作业运行ruff check --diff .（只展示差异不修改），mypy作业运行mypy并缓存.mypy_cache以加速。

运行样式检查（可能自动修改文件）：

make style

对应的实现（Makefile）：

style: ruff format . ruff check --fix .

注意make style会实际修改代码（先格式化再自动修复 lint 问题），因此适合在提交前作为自动整理步骤运行；而make quality只读检查，适合在提交后验证。Ruff 的规则集在 pyproject.toml 中配置：启用E/W/F/I/N/Q/C4/T10/LOG等规则族与 pydocstyle 规则，行宽上限 120，并针对模型、数据集、测试等目录做了 per-file 豁免（如tests/**、scripts/**忽略 pydocstyle 规则D）。Ruff 的isort配置还指定了doctr、app、utils为一等方模块，torch、fastapi、onnxruntime等为第三方模块。

修改文档：本地构建 Sphinx 文档

docTR 的文档由 Sphinx 构建，CI 负责自动构建并部署。在本地验证文档修改：

make docs-single-version

其实现（Makefile）：

docs-single-version: sphinx-build docs/source docs/_build -a

即用sphinx-build从 docs/source 构建到docs/_build目录，-a参数表示全量重建。需要注意的是，未修改过的文件不会重建；如需强制完整重建，可以删除_build目录后重新构建。此外，浏览器可能有缓存，必要时需要清除浏览器缓存才能看到修改效果。

构建完成后，用浏览器打开本地文档入口文件docs/_build/index.html即可预览。

如果只是做最终发布前的完整构建（多版本/带部署逻辑），Makefile 还提供了docs目标：cd docs && bash build.sh，这也是 CI 中 .github/workflows/docs.yml 实际执行的命令——CI 构建成功后会把docs/build部署到gh-pages分支。日常文档小改动验证，使用make docs-single-version即可。

小结：一份可执行的贡献清单

综合仓库中的实际配置，一次规范的 docTR 贡献流程可以归纳为：

1. 反馈先行：通过 Issues 报告 Bug（使用模板并附带collect_env.py输出）或提出特性请求，使用 Discussions 提出疑问；
2. 搭建环境：pip install -e '.[dev]'+pre-commit install，在 Python ≥ 3.11 环境下手动安装 PyTorch；
3. 编写代码：为公共接口补充 Google-style docstring，提交信息遵循 Udacity 风格；
4. 补充测试：在 tests 的common/或pytorch/对应位置新增测试，复用 tests/conftest.py 的 fixture；
5. 本地验证：make test（覆盖率 ≥ 80%）、make style（自动整理）、make quality（lint + 类型检查）、make docs-single-version（文档可构建）；
6. 提交 PR：推送分支并创建 PR，等待 CI（.github/workflows/main.yml 的 pytest 作业、.github/workflows/style.yml 的 ruff/mypy 作业）全部通过。

这套流程的所有环节都能在仓库中找到对应的源码或配置文件依据，照着执行即可让本地开发体验与 CI 保持严格一致，避免"本地通过、CI 挂掉"的反复。

• 人工智能
• 深度学习
• 计算机视觉
• OCR