Skip to content

Commit 3ed3f7e

Browse files
Charliechen114514Charliechen114514
committed
fix features
1 parent 75ff139 commit 3ed3f7e

772 files changed

Lines changed: 77001 additions & 8038 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,4 @@ jobs:
4848
uses: peaceiris/actions-gh-pages@v4
4949
with:
5050
github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub 自动提供的 token
51-
publish_dir: ./site # MkDocs 构建输出目录
51+
publish_dir: ./site # MkDocs 构建输出目录

‎.github/workflows/lint.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Documentation Lint Workflow
2+
# Runs markdown linting and frontmatter validation on PRs
3+
4+
name: Lint Documentation
5+
6+
on:
7+
push:
8+
branches: [main]
9+
pull_request:
10+
branches: [main]
11+
12+
jobs:
13+
markdown-lint:
14+
name: Markdown Lint
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
21+
- name: Run markdownlint
22+
uses: articulate/markdownlint-action@v1
23+
with:
24+
config: .markdownlint.json
25+
files: 'tutorial/**/*.md'
26+
ignore: 'tutorial/**/index.md'
27+
28+
validate-frontmatter:
29+
name: Validate Frontmatter
30+
runs-on: ubuntu-latest
31+
32+
steps:
33+
- name: Checkout repository
34+
uses: actions/checkout@v4
35+
36+
- name: Set up Python
37+
uses: actions/setup-python@v5
38+
with:
39+
python-version: '3.11'
40+
41+
- name: Install dependencies
42+
run: |
43+
pip install pyyaml
44+
45+
- name: Validate frontmatter
46+
run: |
47+
python scripts/validate_frontmatter.py

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
# AI
2-
.claude
2+
.claude

‎.markdownlint.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"default": true,
3+
"MD013": false,
4+
"MD024": {
5+
"siblings_only": true
6+
},
7+
"MD033": false,
8+
"MD041": false,
9+
"MD012": {
10+
"maximum": 3
11+
},
12+
"MD004": {
13+
"style": "dash"
14+
},
15+
"MD007": {
16+
"indent": 2,
17+
"start_indented": false
18+
},
19+
"MD001": false,
20+
"MD025": false,
21+
"MD035": false,
22+
"MD036": false,
23+
"MD060": false
24+
}

‎.pre-commit-config.yaml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Pre-commit hooks configuration
2+
# Install: pip install pre-commit
3+
# Enable: pre-commit install
4+
5+
repos:
6+
# Markdown linting
7+
- repo: https://github.com/igorshubovych/markdownlint-cli
8+
rev: v0.38.0
9+
hooks:
10+
- id: markdownlint
11+
args: ['--config', '.markdownlint.json']
12+
files: '^tutorial/.*\.md$'
13+
exclude: '^tutorial/.*\bindex\.md$'
14+
15+
# Frontmatter validation (local hook)
16+
- repo: local
17+
hooks:
18+
- id: validate-frontmatter
19+
name: Validate article frontmatter
20+
entry: scripts/validate_frontmatter.py
21+
language: python
22+
files: '^tutorial/核心：现代嵌入式C++教程/.*\.md$'
23+
exclude: '(index\.md|tags\.md)$'
24+
pass_filenames: false
25+
26+
# Check for added large files
27+
- repo: https://github.com/pre-commit/pre-commit-hooks
28+
rev: v4.5.0
29+
hooks:
30+
- id: check-added-large-files
31+
args: ['--maxkb=1000']
32+
- id: end-of-file-fixer
33+
- id: trailing-whitespace
34+
files: '^tutorial/.*\.md$'
35+
- id: check-yaml
36+
files: '^\.github/.*\.ya?ml$'

‎.templates/article-template.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: "文章标题"
3+
description: "一句话描述这篇文章的核心内容"
4+
chapter: 0
5+
order: 0
6+
tags:
7+
- 示例标签1
8+
- 示例标签2
9+
difficulty: beginner # beginner | intermediate | advanced
10+
reading_time_minutes: 10
11+
prerequisites:
12+
- "Chapter X: 前置知识章节名称"
13+
related:
14+
- "相关文章标题"
15+
cpp_standard: [11, 14, 17, 20]
16+
---
17+
18+
# 文章标题
19+
20+
## 引言
21+
22+
[简要说明：为什么这个主题重要？在嵌入式开发中有什么应用场景？]
23+
24+
> **学习目标**
25+
> - 完成本章后，你将能够：
26+
> - [ ] 理解核心概念 X
27+
> - [ ] 掌握技术 Y 的使用方法
28+
> - [ ] 了解在实际项目中的应用
29+
30+
## 核心概念
31+
32+
### 第一部分
33+
34+
[正文内容...]
35+
36+
### 第二部分
37+
38+
[正文内容...]
39+
40+
## 代码示例
41+
42+
```cpp
43+
// 可编译运行的代码示例
44+
// Platform: [目标平台，如 STM32F4 / ESP32 / 嵌入式Linux]
45+
// Standard: C++XX
46+
47+
#include <iostream>
48+
49+
int main() {
50+
// 示例代码
51+
return 0;
52+
}
53+
```
54+
55+
**代码说明**：[对代码的关键点进行解释]
56+
57+
## 实战应用
58+
59+
[在嵌入式开发中的实际应用场景]
60+
61+
## 注意事项
62+
63+
[常见陷阱、最佳实践]
64+
65+
### 常见错误
66+
67+
| 错误 | 原因 | 解决方法 |
68+
|------|------|----------|
69+
| xxx | xxx | xxx |
70+
71+
## 小结
72+
73+
[要点回顾]
74+
75+
### 关键要点
76+
77+
- [ ] 要点一
78+
- [ ] 要点二
79+
- [ ] 要点三
80+
81+
## 练习（可选）
82+
83+
[巩固知识的练习题]
84+
85+
### 练习 1
86+
87+
[题目描述]
88+
89+
## 参考资源
90+
91+
- [cppreference 相关章节](https://en.cppreference.com/w/cpp)
92+
- [C++ 标准相关条款]
93+
- [推荐阅读]
94+
95+
---
96+
97+
> **难度自评**：如果你对某个概念感到困惑，请回顾相关的前置知识章节。

‎CONTRIBUTING.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# 贡献指南
2+
3+
感谢你对《现代嵌入式 C++ 教程》的关注！我们欢迎任何形式的贡献，包括但不限于：修正错别字、改进代码示例、完善现有内容、添加新章节等。
4+
5+
## 快速开始
6+
7+
1. Fork 本仓库
8+
2. 创建你的特性分支 (`git checkout -b feature/amazing-feature`)
9+
3. 提交更改 (`git commit -m '添加某功能'`)
10+
4. 推送到分支 (`git push origin feature/amazing-feature`)
11+
5. 创建 Pull Request
12+
13+
## 文章规范
14+
15+
### 文章结构
16+
17+
每篇文章应遵循以下结构（详见 `.templates/article-template.md`）：
18+
19+
```markdown
20+
---
21+
# [FRONTMATTER 元数据]
22+
---
23+
24+
# 标题
25+
26+
## 引言
27+
## 核心概念
28+
## 代码示例
29+
## 实战应用
30+
## 注意事项
31+
## 小结
32+
## 练习（可选）
33+
## 参考资源
34+
```
35+
36+
### Frontmatter 元数据
37+
38+
每篇文章必须包含以下元数据：
39+
40+
| 字段 | 必填 | 说明 |
41+
|------|------|------|
42+
| `title` | 是 | 文章标题 |
43+
| `description` | 是 | 一句话描述文章内容 |
44+
| `chapter` | 是 | 所属章节 (0-10) |
45+
| `order` | 是 | 在章节中的顺序 |
46+
| `tags` | 是 | 标签列表 |
47+
| `difficulty` | 否 | 难度：beginner/intermediate/advanced |
48+
| `reading_time_minutes` | 否 | 预计阅读时间（分钟） |
49+
| `prerequisites` | 否 | 前置知识 |
50+
| `related` | 否 | 相关文章 |
51+
| `cpp_standard` | 否 | 涉及的 C++ 标准 |
52+
53+
### 标签规范
54+
55+
使用以下标签分类：
56+
57+
**概念类**：
58+
- `RAII`、`移动语义`、`零开销抽象`、`编译期计算`、`类型安全`
59+
60+
**语言特性**：
61+
- `constexpr`、`lambda`、`CRTP`、`concepts`、`coroutine`
62+
63+
**模式**：
64+
- `对象池`、`状态机`、`工厂模式`、`策略模式`
65+
66+
**容器**：
67+
- `array`、`span`、`vector`、`map`
68+
69+
**智能指针**：
70+
- `unique_ptr`、`shared_ptr`、`weak_ptr`、`intrusive_ptr`
71+
72+
### 写作风格
73+
74+
1. **语言**：使用清晰、简洁的中文
75+
2. **术语**：首次出现的技术术语应附英文原文
76+
3. **代码注释**：使用中文注释
77+
4. **标题层级**：不超过 4 级（`####`）
78+
5. **篇幅**：每篇文章控制在 1500-3000 字
79+
80+
## 代码规范
81+
82+
### C++ 代码风格
83+
84+
1. 使用现代 C++ 风格（C++11 及以上）
85+
2. 优先使用 `auto`、范围 for 循环等现代特性
86+
3. 遵循嵌入式最佳实践：
87+
- 避免动态内存分配（除非明确说明）
88+
- 注意代码体积和性能影响
89+
- 标注适用的 C++ 标准
90+
91+
```cpp
92+
// 好的示例
93+
// Platform: STM32F4
94+
// Standard: C++17
95+
96+
#include <array>
97+
98+
void process_data(const std::array<uint32_t, 10>& data) {
99+
for (const auto& value : data) {
100+
// 处理数据
101+
}
102+
}
103+
```
104+
105+
### 代码格式
106+
107+
- 使用 4 空格缩进
108+
- 大括号另起一行（Allman 风格）
109+
- 函数名使用 snake_case
110+
- 类名使用 PascalCase
111+
112+
## 添加新文章
113+
114+
1. 复制 `.templates/article-template.md` 作为起点
115+
2. 填写完整的 frontmatter
116+
3. 更新对应章节的 `index.md`，添加新文章链接
117+
4. 确保代码示例可编译
118+
119+
## 文件命名
120+
121+
文章文件名应清晰描述内容：
122+
123+
```
124+
tutorial/核心：现代嵌入式C++教程/Chapter6/
125+
├── 1 RAII在外设管理的作用.md
126+
├── 2 unique_ptr.md
127+
└── 3 shared_ptr.md
128+
```
129+
130+
## 发布前检查清单
131+
132+
提交 PR 前，请确认：
133+
134+
- [ ] Frontmatter 元数据完整
135+
- [ ] 代码示例可编译
136+
- [ ] 无错别字
137+
- [ ] 内部链接有效
138+
- [ ] 标签使用规范
139+
- [ ] 遵循文章模板结构
140+
- [ ] 更新了章节索引（如适用）
141+
142+
## 本地预览
143+
144+
在提交前，建议本地预览文档：
145+
146+
```bash
147+
# 安装依赖
148+
pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-git-revision-date-localized-plugin
149+
150+
# 启动本地服务器
151+
mkdocs serve
152+
153+
# 访问 http://127.0.0.1:8000
154+
```
155+
156+
## 代码审查流程
157+
158+
1. 所有 PR 需要至少一位维护者审核
159+
2. CI 检查必须通过（markdown lint、链接检查）
160+
3. 审核通过后，维护者将合并代码
161+
162+
## 行为准则
163+
164+
- 尊重所有贡献者
165+
- 建设性的反馈和讨论
166+
- 专注于对项目最有利的事情
167+
168+
## 获取帮助
169+
170+
如有问题，请：
171+
- 提交 Issue
172+
- 查看 [GitHub Discussions](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/discussions)
173+
- 发送邮件至：725610365@qq.com
174+
175+
---
176+
177+
再次感谢你的贡献！

0 commit comments

Comments
 (0)