在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

Anduin2017/HowToCook

菜单

概述

相关源文件

本文档提供了 HowToCook 存储库的全面概述，这是一个为程序员设计的社区驱动的食谱项目。该项目旨在解决一个具体问题：传统食谱常常缺乏精确度和清晰度，这对于习惯了正式、结构化语言的程序员来说可能令人沮丧。HowToCook 通过提供标准化格式、精确测量和清晰、逻辑指令的食谱来解决这个问题。

有关食谱组织和分类的详细信息，请参阅 食谱系统。有关贡献工作流程和质量控制流程，请参阅 贡献工作流程。有关部署和基础架构的详细信息，请参阅 部署与基础设施。

系统架构

HowToCook 存储库由几个相互协作的集成系统组成，用于创建、组织、验证和呈现食谱。

高层系统架构

来源：README.md10-14 .github/readme-generate.js1-246 .github/workflows/build.yml1-50 .github/workflows/ci.yml1-18

存储库的核心系统包括

  1. 食谱内容系统：项目的基础，由位于 dishes/ 目录中按类别组织的 Markdown 文件组成。每个食谱都遵循标准化的格式，包含精确的测量和清晰的说明。

  2. 食谱分类系统：在 starsystem/ 目录中使用星级评分系统（1-5 星）按难度对食谱进行分类，提供了浏览食谱的另一种方式。

  3. 文档生成系统：通过 .github/readme-generate.js 脚本自动生成 README.md 文件，更新星级系统索引，并配置 MkDocs 站点。

  4. 质量控制系统：通过 linting 工具和 GitHub Actions 工作流中的自动化检查来确保食谱的质量和一致性。

  5. 贡献系统：通过带有自动化验证的拉取请求来管理添加或修改食谱的过程。

  6. Web 界面：一个由 MkDocs 生成的静态网站，以用户友好的格式呈现食谱，并通过 Docker 容器提供。

食谱组织和内容结构

HowToCook 存储库中的食谱主要通过两种方式组织：按类别类型和按难度级别。

来源：README.md49-379 .github/readme-generate.js12-63 starsystem/1Star.md1-23 starsystem/3Star.md1-111

菜谱类别

存储库将食谱组织到以下主要类别中，每个类别都在 dishes/ 下的各自子目录中：

类别目录描述
蔬菜类vegetable_dish植物性菜肴和蔬菜制备
肉类菜肴meat_dish以肉类为主要成分的菜肴
水产aquatic海鲜和鱼类菜肴
早餐breakfast早餐和餐点
主食staple米饭、面条和其他主食
半成品semi-finished使用半成品食材的食谱
汤soup汤和粥
饮品drink饮料和饮品食谱
调味品condiment酱料、油和其他增味剂
甜点甜点甜点

来源：.github/readme-generate.js12-63 README.md59-380

难度评级系统

食谱还按 1-5 星的难度等级进行分类

  • 1 星：简单的食谱，需要最少的准备（例如，微波炉菜肴）
  • 2 星：基本的食谱，烹饪时间短
  • 3 星：中等复杂的食谱，需要更多的准备
  • 4 星：复杂的食谱，有多个步骤和更长的烹饪时间
  • 5 星：高级食谱，需要显著的技能和时间投入

难度评级保存在 starsystem/ 目录中的索引文件中，这些文件由文档生成系统自动更新。

来源：starsystem/1Star.md1-23 starsystem/3Star.md1-111 starsystem/4Star.md1-79 starsystem/5Star.md1-19

文档和构建系统

HowToCook 存储库使用自动化系统来生成文档和构建网站。

来源：.github/readme-generate.js1-246 .github/templates/readme_template.md1-48 .github/templates/mkdocs_template.yml1-94 Dockerfile1-25

README 生成

脚本 .github/readme-generate.js 是一个 Node.js 脚本，它会：

  1. 扫描 dishes/ 目录以查找所有食谱 Markdown 文件
  2. 按类别和难度级别组织食谱
  3. 使用来自 .github/templates/readme_template.md 的模板生成 README.md 文件
  4. 更新星级系统索引文件（例如，1Star.md、2Star.md 等）
  5. 根据模板生成 MkDocs 配置文件

脚本中的主要功能包括：

  • getAllMarkdown()：递归查找所有 Markdown 文件
  • countStars()：通过计算星号符号来确定食谱难度
  • organizeByStars()：创建难度索引
  • inlineReadmeTemplate()：为 README 格式化食谱条目

来源：.github/readme-generate.js65-123 .github/readme-generate.js125-243

MkDocs 配置

该存储库使用 MkDocs，一个静态站点生成器，从 Markdown 文件构建文档网站。MkDocs 的配置由 readme-generate.js 脚本基于 .github/templates/mkdocs_template.yml 中的模板自动生成。

MkDocs 网站特色：

  • Material 主题，响应式设计
  • 搜索功能
  • PDF 导出功能
  • 自动导航生成
  • 深色/浅色模式切换

来源：.github/templates/mkdocs_template.yml1-94 requirements.txt1-6

质量控制与贡献流程

HowToCook 存储库通过自动化检查和结构化的贡献流程来保持质量。

来源： .github/workflows/ci.yml1-18 .github/workflows/build.yml1-50 package.json16-22 CONTRIBUTING.md1-10

代码检查工具

该存储库使用多种代码检查工具来确保食谱的质量和一致性

  1. markdownlint：确保 Markdown 格式一致性
  2. textlint：检查特定语言问题，尤其针对中文文本
  3. manual_lint.js：一个自定义的代码检查脚本，用于验证食谱的特定要求，例如精确的测量和必需的部分

这些工具通过 CI 工作流在拉取请求时自动运行。

来源： package.json16-22 .markdownlint.json1-8

贡献工作流程

贡献过程遵循以下步骤

  1. 贡献者按照模板编写新食谱或修改现有食谱
  2. 提交的拉取请求已勾选“未获版权”协议
  3. 自动 CI 检查运行代码检查工具
  4. 如果检查通过，人工审阅者将批准并合并更改
  5. 合并后，CD 工作流将更新 README.md 和星级系统索引，然后构建并推送 Docker 镜像

来源： CONTRIBUTING.md1-10 README.md27-31

部署与基础设施

HowToCook 存储库已部署为 Docker 容器，用于提供静态文档站点。

来源： .github/workflows/build.yml1-50 Dockerfile1-25 README.md16-23

Docker 设置

该存储库使用多阶段 Docker 构建过程，该过程在 Dockerfile 中定义

  1. 第一阶段 (lint-env)：安装 Node.js 依赖并运行代码检查
  2. 第二阶段 (python-env)：安装 Python 依赖并构建 MkDocs 站点
  3. 最终阶段：使用静态文件服务器提供生成的站点

用户可以使用 Docker 在本地部署该站点

来源： Dockerfile1-25 README.md16-23

持续部署

持续部署工作流 (.github/workflows/build.yml) 在推送到 master 分支时触发，并执行以下步骤

  1. 生成 README.md 并更新星级系统索引
  2. 构建 Docker 镜像
  3. 将镜像推送到 GitHub Container Registry

部署还包括 cookbook 的 PDF 版本，可通过 /document.pdf URL 访问。

来源： .github/workflows/build.yml1-50 README.md25

总结

HowToCook 存储库是一个结构良好、社区驱动的食谱项目，它利用自动化和质量控制来维护一系列精确、对程序员友好的食谱。该系统的架构将食谱内容管理、文档生成、质量控制和部署整合到一个统一的工作流中，允许社区贡献，同时保持高标准的清晰度和精确度。

来源： README.md10-14