GitHub Actions 工作流

相关源文件

• .github/workflows/build.yml
• .github/workflows/directory_writer.yml
• .github/workflows/project_euler.yml
• .github/workflows/ruff.yml
• .github/workflows/sphinx.yml
• .pre-commit-config.yaml
• DIRECTORY.md
• cellular_automata/game_of_life.py
• data_structures/heap/heap_generic.py
• data_structures/trie/radix_tree.py
• data_structures/trie/trie.py
• graphs/edmonds_karp_multiple_source_and_sink.py
• graphs/eulerian_path_and_circuit_for_undirected_graph.py
• graphs/frequent_pattern_graph_miner.py
• graphs/markov_chain.py
• graphs/tarjans_scc.py
• maths/numerical_analysis/proper_fractions.py
• maths/radix2_fft.py
• physics/newtons_second_law_of_motion.py
• physics/speeds_of_gas_molecules.py
• project_euler/problem_070/__init__.py
• project_euler/problem_070/sol1.py
• pyproject.toml
• requirements.txt
• sorts/msd_radix_sort.py
• strings/aho_corasick.py
• strings/min_cost_string_conversion.py
• uv.lock
• web_programming/get_top_hn_posts.py

此页面介绍了 TheAlgorithms/Python 仓库中自动化测试、代码质量验证、文档生成和欧拉项目（Project Euler）解决方案验证的 CI/CD 工作流。这些工作流确保了代码质量并为所有贡献提供了全面的验证。

概述

TheAlgorithms/Python 仓库使用五个主要的 GitHub Actions 工作流

1. 构建与测试 (build.yml) - 核心测试、覆盖率和目录生成
2. 代码质量 (ruff.yml) - 代码检查与格式化验证
3. 文档生成 (sphinx.yml) - API 文档构建与部署
4. 目录管理 (directory_writer.yml) - 自动更新 DIRECTORY.md
5. 欧拉项目验证 (project_euler.yml) - 解决方案正确性验证

这些工作流协同工作，以维护代码质量、确保测试覆盖率，并为所有仓库贡献提供自动化验证。

来源：.github/workflows/build.yml .github/workflows/ruff.yml .github/workflows/sphinx.yml .github/workflows/directory_writer.yml .github/workflows/project_euler.yml

CI/CD 工作流架构

工作流集成概述

来源：.github/workflows/build.yml3-6 .github/workflows/ruff.yml3-9 .github/workflows/sphinx.yml3-10 .github/workflows/directory_writer.yml4 .github/workflows/project_euler.yml1-9

核心构建与测试工作流 (build.yml)

build 工作流是主要的 CI/CD 流水线，负责运行全面的测试并生成必要的构建产物。

构建工作流配置

该工作流排除了需要额外依赖项或存在已知问题的特定文件

排除的文件	原因
computer_vision/cnn_classification.py	TensorFlow 依赖
dynamic_programming/k_means_clustering_tensorflow.py	TensorFlow 依赖
machine_learning/lstm/lstm_prediction.py	复杂的机器学习依赖
quantum/q_fourier_transform.py	量子计算依赖
project_euler/	由单独的工作流处理

来源：.github/workflows/build.yml9-37

代码质量工作流 (ruff.yml)

ruff 工作流提供快速的 Python 代码检查和格式化验证。

Ruff 工作流步骤

该工作流使用 uvx ruff check，并结合 GitHub 输出格式，在拉取请求上提供内联注释。ruff 配置定义在 pyproject.toml49-158 中，包含广泛的规则选择和按文件忽略设置。

来源：.github/workflows/ruff.yml

文档工作流

Sphinx 文档构建 (sphinx.yml)

Sphinx 工作流负责构建 API 文档并将其部署到 GitHub Pages。

Sphinx 工作流任务

部署任务仅在推送到 master 分支时运行，而不是在拉取请求时运行，以确保文档更改在部署前经过审查。

来源：.github/workflows/sphinx.yml24-50

目录管理 (directory_writer.yml)

directory_writer 工作流在添加新算法时自动更新 DIRECTORY.md。

目录写入器流程

该工作流使用 fetch-depth: 0 来获取完整的 git 历史记录，并强制推送更改以确保 DIRECTORY.md 保持最新。

来源：.github/workflows/directory_writer.yml6-25

欧拉项目验证工作流 (project_euler.yml)

欧拉项目工作流为数学问题解决方案提供专门的答案验证。

欧拉项目工作流结构

该工作流包含两个并行任务

• project-euler: 对欧拉项目解决方案运行标准测试
• validate-solutions: 使用 scripts/validate_solutions.py 验证解决方案的正确性

来源：.github/workflows/project_euler.yml13-35

欧拉项目依赖

欧拉项目验证使用 pyproject.toml 中定义的专用依赖组

此最小依赖集用于验证解决方案，无需完整的项目依赖。

来源：pyproject.toml44-47

工作流依赖与集成

跨工作流的依赖管理

所有工作流都使用 uv 进行快速、可靠的依赖管理，并支持不同的依赖组

工作流	依赖组	目的
build.yml	--group=test	核心测试依赖
sphinx.yml	--group=docs	文档生成
project_euler.yml	--group=euler-validate --group=test	最小验证设置
ruff.yml	无（使用 uvx）	独立代码检查

来源：.github/workflows/build.yml21 .github/workflows/sphinx.yml34 .github/workflows/project_euler.yml22 .github/workflows/ruff.yml16

运行器配置

这些工作流使用针对其工作负载优化的不同 GitHub 托管运行器

来源：.github/workflows/build.yml10 .github/workflows/sphinx.yml26 .github/workflows/directory_writer.yml7 .github/workflows/project_euler.yml15

工作流触发模式与调度

触发策略概述

这些工作流使用针对其特定目的优化的不同触发模式

工作流	触发器	频率	目的
build.yml	pull_request, schedule	每日 + PR	持续验证
ruff.yml	推送到 master 的 push/pull_request	每次提交/PR	代码质量门
sphinx.yml	推送到 master 的 push/pull_request，workflow_dispatch	每次提交 + 手动	文档更新
directory_writer.yml	push	每次提交	自动维护
project_euler.yml	pull_request（已过滤），schedule	每日 + 过滤的 PR	专业验证

并发控制

Sphinx 工作流实施并发控制以防止多次部署

这确保了文档部署在不相互干扰的情况下完成，同时允许构建任务排队。

来源：.github/workflows/sphinx.yml20-22

安全与权限

工作流权限

不同的工作流需要特定的 GitHub token 权限

Sphinx 工作流使用最严格的权限模型，明确指定 pages: write 和 id-token: write 以实现安全的 GitHub Pages 部署。

来源：.github/workflows/sphinx.yml12-16 .github/workflows/directory_writer.yml20 .github/workflows/project_euler.yml35

验证与质量门

这些工作流实施了多个质量门

1. 代码质量：Ruff 代码检查必须通过才能合并
2. 测试覆盖率：构建工作流验证测试覆盖率
3. 解决方案正确性：欧拉项目验证数学解决方案
4. 文档构建：Sphinx 构建必须成功才能更新文档
5. 目录一致性：自动更新 DIRECTORY.md 确保目录准确性

来源：.github/workflows/ruff.yml .github/workflows/build.yml22-35 .github/workflows/project_euler.yml23-33

贡献者文档要求

贡献者在提交新算法时应遵循特定的文档指南。

贡献者文档清单

• 为所有函数和类包含文档字符串（docstrings）
• 为参数和返回值添加类型提示
• 编写 doctest 以演示用法并验证行为
• 遵循 Python 命名约定
• 提供复杂算法的解释
• 在适当时包含源代码或解释的链接

来源：CONTRIBUTING.md102-124

结论

TheAlgorithms/Python 仓库中的文档生成结合了

1. Sphinx 与 AutoAPI 用于全面的 API 文档
2. 自动生成 DIRECTORY.md 以方便导航
3. 代码级别文档的严格标准
4. Doctest 既用于示例也用于验证
5. 自动化工作流用于构建和部署文档

这些系统共同确保仓库保持良好的文档化，使其对用户和贡献者都易于访问。