mirror of
https://github.com/openmlsys/openmlsys-zh.git
synced 2026-03-21 04:27:33 +08:00
refactor: split CONTRIBUTING docs into separate CN/EN files (#503)
Split each bilingual CONTRIBUTING file into _en.md and _zh.md variants: - CONTRIBUTING.md → CONTRIBUTING_en.md + CONTRIBUTING_zh.md - style.md → style_en.md + style_zh.md - info.md → info_en.md + info_zh.md - issue.md → issue_en.md + issue_zh.md - reference_guide.md → reference_guide_en.md + reference_guide_zh.md terminology.md kept as-is (bilingual lookup table by nature). Update README.md to link to _zh.md files, README_EN.md to _en.md files. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yeqi Huang
@@ -76,7 +76,7 @@ After modifying source files under `zh_chapters/` or `en_chapters/`, the browser
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style.md)**.
|
||||
For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style_en.md)**.
|
||||
|
||||
---
|
||||
|
||||
@@ -122,132 +122,3 @@ Add a BibTeX entry to `mlsys.bib`, then cite it in the body text using `:cite:`k
|
||||
**Q: The build says it cannot find an image — what should I do?**
|
||||
|
||||
Check that the image path starts with `../img/` (relative to the chapter directory) and that the image file has been committed to the `img/` directory.
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# 贡献指南
|
||||
|
||||
> **注意：** 本项目的 v1 版本已归档（位于 `v1/` 目录），不再接受新的贡献。请将所有内容贡献提交至 v2（`v2/` 目录）。
|
||||
|
||||
---
|
||||
|
||||
## 仓库结构说明
|
||||
|
||||
```
|
||||
openmlsys/
|
||||
├── v2/ # 第二版（当前活跃版本，接受贡献）
|
||||
│ ├── zh_chapters/ # 中文章节源文件
|
||||
│ │ ├── 00_chapter_preface/ # 各章目录（数字前缀 + 名称）
|
||||
│ │ ├── 01_chapter_introduction/
|
||||
│ │ ├── ...
|
||||
│ │ ├── index.md # 全书首页
|
||||
│ │ └── SUMMARY.md # 由脚本自动生成，勿手动编辑
|
||||
│ ├── en_chapters/ # 英文章节源文件（结构与中文章节一致）
|
||||
│ ├── config/
|
||||
│ │ ├── en_config/ # 英文版 mdBook 配置
|
||||
│ │ └── zh_config/ # 中文版 mdBook 配置
|
||||
├── v1/ # 第一版（已归档）
|
||||
├── CONTRIBUTING/ # 贡献指南与相关文档
|
||||
├── img/ # 全书共享图片资源
|
||||
├── references/ # 参考文献目录
|
||||
├── tools/ # 构建与预处理脚本
|
||||
│ ├── prepare_mdbook.py # 核心预处理：解析自定义语法、生成 SUMMARY
|
||||
│ └── mdbook_preprocessor.py # mdBook 预处理器入口
|
||||
└── build_mdbook_v2.sh # v2 一键构建脚本
|
||||
```
|
||||
|
||||
**重要**：`SUMMARY.md` 由 `tools/prepare_mdbook_zh.py` 根据 `index.md` 中的 `toc` 块自动生成，**请勿手动修改**。
|
||||
|
||||
---
|
||||
|
||||
## 环境准备
|
||||
|
||||
```bash
|
||||
# 1. 安装 Rust 工具链
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
# 2. 安装 mdBook
|
||||
cargo install mdbook
|
||||
|
||||
# 3. 克隆仓库（需预先安装 Python 3）
|
||||
git clone https://github.com/openmlsys/openmlsys.git
|
||||
cd openmlsys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 本地构建
|
||||
|
||||
### 构建 v2 中英文双版本
|
||||
|
||||
```bash
|
||||
bash build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
构建产物输出至 `.mdbook-v2-zh/book`（中文）和 `.mdbook-v2/book`（英文）。
|
||||
|
||||
### 实时预览
|
||||
|
||||
```bash
|
||||
# 中文版实时预览
|
||||
cd v2/config/zh_config && mdbook serve --open
|
||||
# 英文版实时预览
|
||||
cd v2/config/en_config && mdbook serve --open
|
||||
```
|
||||
|
||||
修改 `zh_chapters/` 或 `en_chapters/` 下的源文件后，浏览器将自动刷新。
|
||||
|
||||
> **注意**：预处理脚本会在每次构建时重新生成 `SUMMARY.md`，如遇构建报错请先检查 `index.md` 中 `toc` 块的格式是否正确。
|
||||
|
||||
---
|
||||
|
||||
## 写作规范
|
||||
|
||||
详细的自定义语法（公式、图片标签、文献引用、代码块等）及图片规范，请参阅 **[写作样式规范](style.md)**。
|
||||
|
||||
---
|
||||
|
||||
## 提交流程
|
||||
|
||||
1. **Fork** 本仓库并创建功能分支：
|
||||
```bash
|
||||
git checkout -b feat/chapter-xxx-section-yyy
|
||||
```
|
||||
|
||||
2. **本地构建验证**：修改完成后运行 `bash build_mdbook_v2.sh`，确保无报错
|
||||
|
||||
3. **提交代码**：遵循语义化提交信息
|
||||
```bash
|
||||
git commit -m "feat(zh): 新增第X章第Y节内容"
|
||||
git commit -m "feat(en): Add content for chapter X section Y"
|
||||
git commit -m "ci: update main.yml"
|
||||
```
|
||||
常用前缀：`feat`（新内容）、`fix`（修正错误）、`refactor`（重组结构）、`style`（格式调整）、`ci`（构建流程更新）
|
||||
|
||||
4. **发起 Pull Request**：目标分支为 `main`，请使用 PR 模板：
|
||||
|
||||
- [中文 PR 模板](.github/PULL_REQUEST_TEMPLATE/zh.md)
|
||||
- [英文 PR 模板](.github/PULL_REQUEST_TEMPLATE/en.md)
|
||||
|
||||
5. **代码审查**：PR要求至少有一位非本人Contributor进行检查，且github action将会自动验证新增内容是否可以编译通过
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q：如何添加新章节？**
|
||||
|
||||
- 在 `v2/zh_chapters/` 下新建 `chapter_<名称>/` 目录
|
||||
- 创建 `index.md`，在其中使用 `toc` 块列出各节
|
||||
- 在全书 `v2/zh_chapters/index.md` 的 `toc` 块中注册新章节
|
||||
- 确保本地构建通过后再提交 PR
|
||||
|
||||
**Q：参考文献如何添加？**
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的文献条目，然后在正文中使用 `:cite:`key`` 引用。
|
||||
|
||||
**Q：构建时提示找不到图片怎么处理？**
|
||||
|
||||
检查图片路径是否以 `../img/` 开头（相对于章节目录），以及图片文件是否已提交至 `img/` 目录。
|
||||
124
CONTRIBUTING/CONTRIBUTING_zh.md
Normal file
124
CONTRIBUTING/CONTRIBUTING_zh.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 贡献指南
|
||||
|
||||
> **注意：** 本项目的 v1 版本已归档（位于 `v1/` 目录），不再接受新的贡献。请将所有内容贡献提交至 v2（`v2/` 目录）。
|
||||
|
||||
---
|
||||
|
||||
## 仓库结构说明
|
||||
|
||||
```
|
||||
openmlsys/
|
||||
├── v2/ # 第二版（当前活跃版本，接受贡献）
|
||||
│ ├── zh_chapters/ # 中文章节源文件
|
||||
│ │ ├── 00_chapter_preface/ # 各章目录（数字前缀 + 名称）
|
||||
│ │ ├── 01_chapter_introduction/
|
||||
│ │ ├── ...
|
||||
│ │ ├── index.md # 全书首页
|
||||
│ │ └── SUMMARY.md # 由脚本自动生成，勿手动编辑
|
||||
│ ├── en_chapters/ # 英文章节源文件（结构与中文章节一致）
|
||||
│ ├── config/
|
||||
│ │ ├── en_config/ # 英文版 mdBook 配置
|
||||
│ │ └── zh_config/ # 中文版 mdBook 配置
|
||||
├── v1/ # 第一版（已归档）
|
||||
├── CONTRIBUTING/ # 贡献指南与相关文档
|
||||
├── img/ # 全书共享图片资源
|
||||
├── references/ # 参考文献目录
|
||||
├── tools/ # 构建与预处理脚本
|
||||
│ ├── prepare_mdbook.py # 核心预处理：解析自定义语法、生成 SUMMARY
|
||||
│ └── mdbook_preprocessor.py # mdBook 预处理器入口
|
||||
└── build_mdbook_v2.sh # v2 一键构建脚本
|
||||
```
|
||||
|
||||
**重要**：`SUMMARY.md` 由 `tools/prepare_mdbook_zh.py` 根据 `index.md` 中的 `toc` 块自动生成，**请勿手动修改**。
|
||||
|
||||
---
|
||||
|
||||
## 环境准备
|
||||
|
||||
```bash
|
||||
# 1. 安装 Rust 工具链
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
# 2. 安装 mdBook
|
||||
cargo install mdbook
|
||||
|
||||
# 3. 克隆仓库（需预先安装 Python 3）
|
||||
git clone https://github.com/openmlsys/openmlsys.git
|
||||
cd openmlsys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 本地构建
|
||||
|
||||
### 构建 v2 中英文双版本
|
||||
|
||||
```bash
|
||||
bash build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
构建产物输出至 `.mdbook-v2-zh/book`（中文）和 `.mdbook-v2/book`（英文）。
|
||||
|
||||
### 实时预览
|
||||
|
||||
```bash
|
||||
# 中文版实时预览
|
||||
cd v2/config/zh_config && mdbook serve --open
|
||||
# 英文版实时预览
|
||||
cd v2/config/en_config && mdbook serve --open
|
||||
```
|
||||
|
||||
修改 `zh_chapters/` 或 `en_chapters/` 下的源文件后，浏览器将自动刷新。
|
||||
|
||||
> **注意**：预处理脚本会在每次构建时重新生成 `SUMMARY.md`，如遇构建报错请先检查 `index.md` 中 `toc` 块的格式是否正确。
|
||||
|
||||
---
|
||||
|
||||
## 写作规范
|
||||
|
||||
详细的自定义语法（公式、图片标签、文献引用、代码块等）及图片规范，请参阅 **[写作样式规范](style_zh.md)**。
|
||||
|
||||
---
|
||||
|
||||
## 提交流程
|
||||
|
||||
1. **Fork** 本仓库并创建功能分支：
|
||||
```bash
|
||||
git checkout -b feat/chapter-xxx-section-yyy
|
||||
```
|
||||
|
||||
2. **本地构建验证**：修改完成后运行 `bash build_mdbook_v2.sh`，确保无报错
|
||||
|
||||
3. **提交代码**：遵循语义化提交信息
|
||||
```bash
|
||||
git commit -m "feat(zh): 新增第X章第Y节内容"
|
||||
git commit -m "feat(en): Add content for chapter X section Y"
|
||||
git commit -m "ci: update main.yml"
|
||||
```
|
||||
常用前缀：`feat`（新内容）、`fix`（修正错误）、`refactor`（重组结构）、`style`（格式调整）、`ci`（构建流程更新）
|
||||
|
||||
4. **发起 Pull Request**：目标分支为 `main`，请使用 PR 模板：
|
||||
|
||||
- [中文 PR 模板](.github/PULL_REQUEST_TEMPLATE/zh.md)
|
||||
- [英文 PR 模板](.github/PULL_REQUEST_TEMPLATE/en.md)
|
||||
|
||||
5. **代码审查**：PR要求至少有一位非本人Contributor进行检查，且github action将会自动验证新增内容是否可以编译通过
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q：如何添加新章节？**
|
||||
|
||||
- 在 `v2/zh_chapters/` 下新建 `chapter_<名称>/` 目录
|
||||
- 创建 `index.md`，在其中使用 `toc` 块列出各节
|
||||
- 在全书 `v2/zh_chapters/index.md` 的 `toc` 块中注册新章节
|
||||
- 确保本地构建通过后再提交 PR
|
||||
|
||||
**Q：参考文献如何添加？**
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的文献条目，然后在正文中使用 `:cite:`key`` 引用。
|
||||
|
||||
**Q：构建时提示找不到图片怎么处理？**
|
||||
|
||||
检查图片路径是否以 `../img/` 开头（相对于章节目录），以及图片文件是否已提交至 `img/` 目录。
|
||||
@@ -1,53 +0,0 @@
|
||||
# Build & Environment Guide / 环境安装与编译指南
|
||||
|
||||
## Environment Setup / 环境安装
|
||||
|
||||
The book is deployed on GitHub using mdbook. We recommend installing mdbook via Rust's native package manager cargo.
|
||||
|
||||
机器学习系统书籍部署在GitHub是依赖于mdbook工具实现的。我们推荐使用rust的原生包管理器cargo安装mdbook。
|
||||
|
||||
```bash
|
||||
# Install Rust toolchain to get cargo / 安装rust工具链，获取cargo
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
## Building HTML / 编译HTML版本
|
||||
|
||||
Clone the [openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) repository first. All build commands should be run from the repository root.
|
||||
|
||||
在编译前先下载[openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) ， 所有的编译命令都在这个文件目录内执行。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openmlsys/openmlsys-zh.git
|
||||
cd openmlsys-zh
|
||||
```
|
||||
|
||||
Build HTML using mdbook. Please use the build scripts to ensure the homepage is correctly merged into the book.
|
||||
|
||||
使用mdbook工具编译HTML。 请尽量使用build脚本进行编译，保证首页正确合并到书籍中去。
|
||||
|
||||
```bash
|
||||
sh build_mdbook_v1.sh
|
||||
sh build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
Build outputs are placed in `.mdbook-v2/book` (English) and `.mdbook-v2-zh/book` (Chinese). The `tools/assemble_docs_publish_tree.py` script assembles the final bilingual publication tree, which is then copied to openmlsys.github.io for deployment.
|
||||
|
||||
生成的html会在`.mdbook-v2/book`或者`.mdbook-v2-zh/book`下。此时我们可以使用`tools/assemble_docs_publish_tree.py`组装最终的双语发布版本，然后将其拷贝至openmlsys.github.io的docs发布。
|
||||
|
||||
For the detailed deployment workflow, see `.github/workflows/update_docs.yml`.
|
||||
|
||||
具体工作流可以参考`.github/workflows/update_docs.yml`
|
||||
|
||||
## Style Guide / 样式规范
|
||||
|
||||
Please follow the project [style guide](style.md) when contributing.
|
||||
|
||||
贡献请遵照本教程的[样式规范](style.md)。
|
||||
|
||||
## Terminology / 中英文术语对照
|
||||
|
||||
Please refer to the [terminology guide](terminology.md) for translations.
|
||||
|
||||
翻译请参照[中英文术语对照](terminology.md)。
|
||||
39
CONTRIBUTING/info_en.md
Normal file
39
CONTRIBUTING/info_en.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Build & Environment Guide
|
||||
|
||||
## Environment Setup
|
||||
|
||||
The book is deployed on GitHub using mdbook. We recommend installing mdbook via Rust's native package manager cargo.
|
||||
|
||||
```bash
|
||||
# Install Rust toolchain to get cargo
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
## Building HTML
|
||||
|
||||
Clone the [openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) repository first. All build commands should be run from the repository root.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openmlsys/openmlsys-zh.git
|
||||
cd openmlsys-zh
|
||||
```
|
||||
|
||||
Build HTML using mdbook. Please use the build scripts to ensure the homepage is correctly merged into the book.
|
||||
|
||||
```bash
|
||||
sh build_mdbook_v1.sh
|
||||
sh build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
Build outputs are placed in `.mdbook-v2/book` (English) and `.mdbook-v2-zh/book` (Chinese). The `tools/assemble_docs_publish_tree.py` script assembles the final bilingual publication tree, which is then copied to openmlsys.github.io for deployment.
|
||||
|
||||
For the detailed deployment workflow, see `.github/workflows/update_docs.yml`.
|
||||
|
||||
## Style Guide
|
||||
|
||||
Please follow the project [style guide](style_en.md) when contributing.
|
||||
|
||||
## Terminology
|
||||
|
||||
Please refer to the [terminology guide](terminology.md) for translations.
|
||||
39
CONTRIBUTING/info_zh.md
Normal file
39
CONTRIBUTING/info_zh.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# 环境安装与编译指南
|
||||
|
||||
## 环境安装
|
||||
|
||||
机器学习系统书籍部署在GitHub是依赖于mdbook工具实现的。我们推荐使用rust的原生包管理器cargo安装mdbook。
|
||||
|
||||
```bash
|
||||
# 安装rust工具链，获取cargo
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
## 编译HTML版本
|
||||
|
||||
在编译前先下载[openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) ， 所有的编译命令都在这个文件目录内执行。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openmlsys/openmlsys-zh.git
|
||||
cd openmlsys-zh
|
||||
```
|
||||
|
||||
使用mdbook工具编译HTML。 请尽量使用build脚本进行编译，保证首页正确合并到书籍中去。
|
||||
|
||||
```bash
|
||||
sh build_mdbook_v1.sh
|
||||
sh build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
生成的html会在`.mdbook-v2/book`或者`.mdbook-v2-zh/book`下。此时我们可以使用`tools/assemble_docs_publish_tree.py`组装最终的双语发布版本，然后将其拷贝至openmlsys.github.io的docs发布。
|
||||
|
||||
具体工作流可以参考`.github/workflows/update_docs.yml`
|
||||
|
||||
## 样式规范
|
||||
|
||||
贡献请遵照本教程的[样式规范](style_zh.md)。
|
||||
|
||||
## 中英文术语对照
|
||||
|
||||
翻译请参照[中英文术语对照](terminology.md)。
|
||||
@@ -1,19 +0,0 @@
|
||||
# Issue Labels / Issue 的 label
|
||||
|
||||
Our issues use the following labels:
|
||||
|
||||
目前我们的issue主要有如下label:
|
||||
|
||||
- **great suggestion**: The issue is a good writing suggestion from a user / 表示该issue是用户为本书的内容提供的写作建议，并且该建议是一个很好的建议
|
||||
- **discussion**: The issue is a discussion about the content, or a suggestion still under deliberation / 表示该issue是用户针对文章内容进行特定讨论，或用户对内容进行了建议并且该建议还处在商讨中
|
||||
- **to be confirmed**: The issue has been assigned to a chapter author who has not yet responded / 表示该issue被assign给了章节作者，但是目前章节作者并没有回复处理这个issue
|
||||
- **confirmed**: The chapter author has confirmed the issue / 表示该issue被章节作者已经确认
|
||||
- **fixed**: The related PR has been approved/merged / 表示该issue相关的pr被approve/merge
|
||||
|
||||
## Typical Issue Lifecycle / 常规状态变换
|
||||
|
||||
A typical content-correction issue follows this lifecycle:
|
||||
|
||||
常规而言，一个针对书籍内容校正的issue的状态变换应该为:
|
||||
|
||||
to be confirmed ----> confirmed ----> fixed
|
||||
15
CONTRIBUTING/issue_en.md
Normal file
15
CONTRIBUTING/issue_en.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Issue Labels
|
||||
|
||||
Our issues use the following labels:
|
||||
|
||||
- **great suggestion**: The issue is a good writing suggestion from a user
|
||||
- **discussion**: The issue is a discussion about the content, or a suggestion still under deliberation
|
||||
- **to be confirmed**: The issue has been assigned to a chapter author who has not yet responded
|
||||
- **confirmed**: The chapter author has confirmed the issue
|
||||
- **fixed**: The related PR has been approved/merged
|
||||
|
||||
## Typical Issue Lifecycle
|
||||
|
||||
A typical content-correction issue follows this lifecycle:
|
||||
|
||||
to be confirmed ----> confirmed ----> fixed
|
||||
15
CONTRIBUTING/issue_zh.md
Normal file
15
CONTRIBUTING/issue_zh.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Issue 的 label
|
||||
|
||||
目前我们的issue主要有如下label:
|
||||
|
||||
- **great suggestion**: 表示该issue是用户为本书的内容提供的写作建议，并且该建议是一个很好的建议
|
||||
- **discussion**: 表示该issue是用户针对文章内容进行特定讨论，或用户对内容进行了建议并且该建议还处在商讨中
|
||||
- **to be confirmed**: 表示该issue被assign给了章节作者，但是目前章节作者并没有回复处理这个issue
|
||||
- **confirmed**: 表示该issue被章节作者已经确认
|
||||
- **fixed**: 表示该issue相关的pr被approve/merge
|
||||
|
||||
## 常规状态变换
|
||||
|
||||
常规而言，一个针对书籍内容校正的issue的状态变换应该为:
|
||||
|
||||
to be confirmed ----> confirmed ----> fixed
|
||||
@@ -1,38 +0,0 @@
|
||||
# Reference Citation Guide / 参考文献引用方式
|
||||
|
||||
All references are maintained in `mlsys.bib`.
|
||||
|
||||
所有参考文献统一维护在 `mlsys.bib` 中。
|
||||
|
||||
## Adding Bibliography Entries / 添加文献条目
|
||||
|
||||
Add a BibTeX entry to `mlsys.bib`. Before adding, search for existing keys to avoid duplicates:
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的条目，添加前请先检索是否已存在同名 key：
|
||||
|
||||
```bibtex
|
||||
@inproceedings{cnn2015,
|
||||
title = {CNN},
|
||||
author = {xxx},
|
||||
year = {2015},
|
||||
keywords = {xxx}
|
||||
}
|
||||
```
|
||||
|
||||
## In-text Citations / 正文引用
|
||||
|
||||
A space is required before the citation directive:
|
||||
|
||||
引用时前面需要有一个空格：
|
||||
|
||||
1. Single reference / 单篇参考文献
|
||||
```
|
||||
This article references the paper :cite:`cnn2015`
|
||||
这篇文章参考了论文 :cite:`cnn2015`
|
||||
```
|
||||
|
||||
2. Multiple references separated by commas / 多篇参考文献用逗号分隔
|
||||
```
|
||||
This article references the papers :cite:`cnn2015,rnn2015`
|
||||
这篇文章参考了论文 :cite:`cnn2015,rnn2015`
|
||||
```
|
||||
30
CONTRIBUTING/reference_guide_en.md
Normal file
30
CONTRIBUTING/reference_guide_en.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Reference Citation Guide
|
||||
|
||||
All references are maintained in `mlsys.bib`.
|
||||
|
||||
## Adding Bibliography Entries
|
||||
|
||||
Add a BibTeX entry to `mlsys.bib`. Before adding, search for existing keys to avoid duplicates:
|
||||
|
||||
```bibtex
|
||||
@inproceedings{cnn2015,
|
||||
title = {CNN},
|
||||
author = {xxx},
|
||||
year = {2015},
|
||||
keywords = {xxx}
|
||||
}
|
||||
```
|
||||
|
||||
## In-text Citations
|
||||
|
||||
A space is required before the citation directive:
|
||||
|
||||
1. Single reference
|
||||
```
|
||||
This article references the paper :cite:`cnn2015`
|
||||
```
|
||||
|
||||
2. Multiple references separated by commas
|
||||
```
|
||||
This article references the papers :cite:`cnn2015,rnn2015`
|
||||
```
|
||||
30
CONTRIBUTING/reference_guide_zh.md
Normal file
30
CONTRIBUTING/reference_guide_zh.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# 参考文献引用方式
|
||||
|
||||
所有参考文献统一维护在 `mlsys.bib` 中。
|
||||
|
||||
## 添加文献条目
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的条目，添加前请先检索是否已存在同名 key：
|
||||
|
||||
```bibtex
|
||||
@inproceedings{cnn2015,
|
||||
title = {CNN},
|
||||
author = {xxx},
|
||||
year = {2015},
|
||||
keywords = {xxx}
|
||||
}
|
||||
```
|
||||
|
||||
## 正文引用
|
||||
|
||||
引用时前面需要有一个空格：
|
||||
|
||||
1. 单篇参考文献
|
||||
```
|
||||
这篇文章参考了论文 :cite:`cnn2015`
|
||||
```
|
||||
|
||||
2. 多篇参考文献用逗号分隔
|
||||
```
|
||||
这篇文章参考了论文 :cite:`cnn2015,rnn2015`
|
||||
```
|
||||
@@ -178,188 +178,3 @@ Example citations in body text:
|
||||
This chapter references the paper :cite:`cnn2015`.
|
||||
Multiple citations: :cite:`cnn2015,rnn2015`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# 写作样式规范
|
||||
|
||||
本文档规定了 v2 章节内容的写作格式与样式要求。所有贡献者在撰写或修改内容时请遵循以下规范。
|
||||
|
||||
> **注意：** LaTeX 转 Markdown 的工作流已**废弃**。v2 中所有内容直接使用 Markdown 书写，无需通过 Pandoc 等工具转换。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [文件结构](#文件结构)
|
||||
- [自定义语法](#自定义语法)
|
||||
- [图片规范](#图片规范)
|
||||
- [表格规范](#表格规范)
|
||||
- [代码块规范](#代码块规范)
|
||||
- [参考文献](#参考文献)
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
- 每章对应 `v2/zh_chapters/<nn>_chapter_<名称>/` 目录（如 `02_chapter_programming_and_graph/`）
|
||||
- 章节入口为 `index.md`，各节内容放在同目录下的独立 `.md` 文件中
|
||||
- 在 `index.md` 中使用 `toc` 块声明本章的节结构（脚本据此自动生成 `SUMMARY.md`）：
|
||||
|
||||
```markdown
|
||||
```toc
|
||||
:maxdepth: 2
|
||||
|
||||
section_one
|
||||
section_two
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自定义语法
|
||||
|
||||
本项目的预处理器支持以下扩展 Markdown 语法，**请严格遵守**以确保构建正确。
|
||||
|
||||
### 行内公式
|
||||
|
||||
```markdown
|
||||
模型学习映射 $f: \mathcal{X} \rightarrow \mathcal{Y}$。
|
||||
```
|
||||
|
||||
### 行间公式与标签
|
||||
|
||||
公式标签格式为 `:eqlabel:`<标签名>``，标签名建议以语言后缀结尾（如 `-zh`）以避免中英文冲突：
|
||||
|
||||
```markdown
|
||||
$$
|
||||
\mathcal{L}_{CE} = -\sum_{i=1}^{N} y_i \log(\hat{y}_i)
|
||||
$$
|
||||
:eqlabel:`eq-cross-entropy-zh`
|
||||
```
|
||||
|
||||
引用公式：`:eqref:`eq-cross-entropy-zh``
|
||||
|
||||
### 图片与标签
|
||||
|
||||
```markdown
|
||||
|
||||
:width:`600px`
|
||||
:label:`figure-label-zh`
|
||||
```
|
||||
|
||||
引用图片：`:numref:`figure-label-zh``
|
||||
|
||||
### 章节引用
|
||||
|
||||
在节标题后添加标签：
|
||||
|
||||
```markdown
|
||||
### 节标题
|
||||
:label:`my-section-zh`
|
||||
```
|
||||
|
||||
引用该节：`:ref:`my-section-zh``
|
||||
|
||||
### 文献引用
|
||||
|
||||
```markdown
|
||||
感知机 :cite:`rosenblatt1958perceptron` 是最早期的神经网络模型之一。
|
||||
```
|
||||
|
||||
多篇文献用逗号分隔：`:cite:`paper1,paper2``
|
||||
|
||||
参考文献条目统一维护在 `mlsys.bib` 中（详见[参考文献](#参考文献)一节）。
|
||||
|
||||
---
|
||||
|
||||
## 图片规范
|
||||
|
||||
### 存放位置
|
||||
|
||||
图片存放于 `img/ch<章节编号>/` 目录下，如 `img/ch01/`。图片文件须随 PR 一起提交。
|
||||
|
||||
### 文件命名
|
||||
|
||||
使用英文小写加连字符，如 `framework-architecture.png`。
|
||||
|
||||
### 格式
|
||||
|
||||
| 格式 | 适用场景 |
|
||||
|------|---------|
|
||||
| SVG | 自行绘制的流程图、示意图（矢量，缩放不失真），需去除白色背景 |
|
||||
| PNG | 截图、照片、含复杂渐变的图片 |
|
||||
|
||||
推荐使用以下工具绘制后导出：
|
||||
|
||||
- **[Excalidraw MCP](https://github.com/excalidraw/excalidraw-mcp)** — 官方 Excalidraw MCP 服务器，支持 AI 辅助绘图（远程地址：`https://mcp.excalidraw.com`）
|
||||
- **[interactive-drawer](https://github.com/anyin233/interactive-drawer)** — 自托管 Excalidraw MCP，支持会话管理
|
||||
- **PPT** — PowerPoint，参见 [Pic-Instruction/](Pic-Instruction/) 获取模板
|
||||
- **draw.io** — 免费在线绘图工具
|
||||
|
||||
**不得使用网络图片**（版权风险）。
|
||||
|
||||
### 分辨率与尺寸
|
||||
|
||||
- 推荐分辨率：≥ 150 dpi
|
||||
- 宽度不超过 1200 px
|
||||
- Markdown 中通过 `:width:` 指定显示宽度（建议 600–800 px）
|
||||
|
||||
### 排版
|
||||
|
||||
相邻两张图之间须有足够的文字说明，避免图片紧邻。
|
||||
|
||||
---
|
||||
|
||||
## 表格规范
|
||||
|
||||
使用标准 Markdown 表格语法，并为需要引用的表格打标签：
|
||||
|
||||
```markdown
|
||||
| 列名 1 | 列名 2 | 列名 3 |
|
||||
|--------|--------|--------|
|
||||
| 值 1 | 值 2 | 值 3 |
|
||||
:label:`table-label-zh`
|
||||
```
|
||||
|
||||
引用表格：`:numref:`table-label-zh``
|
||||
|
||||
---
|
||||
|
||||
## 代码块规范
|
||||
|
||||
使用标准 Markdown 围栏代码块，必须标注语言类型：
|
||||
|
||||
````markdown
|
||||
```python
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
```
|
||||
````
|
||||
|
||||
常用语言标识：`python`、`bash`、`cpp`、`markdown`、`text`。
|
||||
|
||||
---
|
||||
|
||||
## 参考文献
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的文献条目：
|
||||
|
||||
```bibtex
|
||||
@inproceedings{key2015,
|
||||
title = {Title of the Paper},
|
||||
author = {Author, A. and Author, B.},
|
||||
year = {2015}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：`mlsys.bib` 中不可出现重复的 key，添加前请先检索是否已存在。
|
||||
|
||||
正文引用示例：
|
||||
|
||||
```markdown
|
||||
这篇文章参考了论文 :cite:`cnn2015`。
|
||||
多篇文献引用：:cite:`cnn2015,rnn2015`。
|
||||
```
|
||||
180
CONTRIBUTING/style_zh.md
Normal file
180
CONTRIBUTING/style_zh.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 写作样式规范
|
||||
|
||||
本文档规定了 v2 章节内容的写作格式与样式要求。所有贡献者在撰写或修改内容时请遵循以下规范。
|
||||
|
||||
> **注意：** LaTeX 转 Markdown 的工作流已**废弃**。v2 中所有内容直接使用 Markdown 书写，无需通过 Pandoc 等工具转换。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [文件结构](#文件结构)
|
||||
- [自定义语法](#自定义语法)
|
||||
- [图片规范](#图片规范)
|
||||
- [表格规范](#表格规范)
|
||||
- [代码块规范](#代码块规范)
|
||||
- [参考文献](#参考文献)
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
- 每章对应 `v2/zh_chapters/<nn>_chapter_<名称>/` 目录（如 `02_chapter_programming_and_graph/`）
|
||||
- 章节入口为 `index.md`，各节内容放在同目录下的独立 `.md` 文件中
|
||||
- 在 `index.md` 中使用 `toc` 块声明本章的节结构（脚本据此自动生成 `SUMMARY.md`）：
|
||||
|
||||
```markdown
|
||||
```toc
|
||||
:maxdepth: 2
|
||||
|
||||
section_one
|
||||
section_two
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自定义语法
|
||||
|
||||
本项目的预处理器支持以下扩展 Markdown 语法，**请严格遵守**以确保构建正确。
|
||||
|
||||
### 行内公式
|
||||
|
||||
```markdown
|
||||
模型学习映射 $f: \mathcal{X} \rightarrow \mathcal{Y}$。
|
||||
```
|
||||
|
||||
### 行间公式与标签
|
||||
|
||||
公式标签格式为 `:eqlabel:`<标签名>``，标签名建议以语言后缀结尾（如 `-zh`）以避免中英文冲突：
|
||||
|
||||
```markdown
|
||||
$$
|
||||
\mathcal{L}_{CE} = -\sum_{i=1}^{N} y_i \log(\hat{y}_i)
|
||||
$$
|
||||
:eqlabel:`eq-cross-entropy-zh`
|
||||
```
|
||||
|
||||
引用公式：`:eqref:`eq-cross-entropy-zh``
|
||||
|
||||
### 图片与标签
|
||||
|
||||
```markdown
|
||||
|
||||
:width:`600px`
|
||||
:label:`figure-label-zh`
|
||||
```
|
||||
|
||||
引用图片：`:numref:`figure-label-zh``
|
||||
|
||||
### 章节引用
|
||||
|
||||
在节标题后添加标签：
|
||||
|
||||
```markdown
|
||||
### 节标题
|
||||
:label:`my-section-zh`
|
||||
```
|
||||
|
||||
引用该节：`:ref:`my-section-zh``
|
||||
|
||||
### 文献引用
|
||||
|
||||
```markdown
|
||||
感知机 :cite:`rosenblatt1958perceptron` 是最早期的神经网络模型之一。
|
||||
```
|
||||
|
||||
多篇文献用逗号分隔：`:cite:`paper1,paper2``
|
||||
|
||||
参考文献条目统一维护在 `mlsys.bib` 中（详见[参考文献](#参考文献)一节）。
|
||||
|
||||
---
|
||||
|
||||
## 图片规范
|
||||
|
||||
### 存放位置
|
||||
|
||||
图片存放于 `img/ch<章节编号>/` 目录下，如 `img/ch01/`。图片文件须随 PR 一起提交。
|
||||
|
||||
### 文件命名
|
||||
|
||||
使用英文小写加连字符，如 `framework-architecture.png`。
|
||||
|
||||
### 格式
|
||||
|
||||
| 格式 | 适用场景 |
|
||||
|------|---------|
|
||||
| SVG | 自行绘制的流程图、示意图（矢量，缩放不失真），需去除白色背景 |
|
||||
| PNG | 截图、照片、含复杂渐变的图片 |
|
||||
|
||||
推荐使用以下工具绘制后导出：
|
||||
|
||||
- **[Excalidraw MCP](https://github.com/excalidraw/excalidraw-mcp)** — 官方 Excalidraw MCP 服务器，支持 AI 辅助绘图（远程地址：`https://mcp.excalidraw.com`）
|
||||
- **[interactive-drawer](https://github.com/anyin233/interactive-drawer)** — 自托管 Excalidraw MCP，支持会话管理
|
||||
- **PPT** — PowerPoint，参见 [Pic-Instruction/](Pic-Instruction/) 获取模板
|
||||
- **draw.io** — 免费在线绘图工具
|
||||
|
||||
**不得使用网络图片**（版权风险）。
|
||||
|
||||
### 分辨率与尺寸
|
||||
|
||||
- 推荐分辨率：≥ 150 dpi
|
||||
- 宽度不超过 1200 px
|
||||
- Markdown 中通过 `:width:` 指定显示宽度（建议 600–800 px）
|
||||
|
||||
### 排版
|
||||
|
||||
相邻两张图之间须有足够的文字说明，避免图片紧邻。
|
||||
|
||||
---
|
||||
|
||||
## 表格规范
|
||||
|
||||
使用标准 Markdown 表格语法，并为需要引用的表格打标签：
|
||||
|
||||
```markdown
|
||||
| 列名 1 | 列名 2 | 列名 3 |
|
||||
|--------|--------|--------|
|
||||
| 值 1 | 值 2 | 值 3 |
|
||||
:label:`table-label-zh`
|
||||
```
|
||||
|
||||
引用表格：`:numref:`table-label-zh``
|
||||
|
||||
---
|
||||
|
||||
## 代码块规范
|
||||
|
||||
使用标准 Markdown 围栏代码块，必须标注语言类型：
|
||||
|
||||
````markdown
|
||||
```python
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
```
|
||||
````
|
||||
|
||||
常用语言标识：`python`、`bash`、`cpp`、`markdown`、`text`。
|
||||
|
||||
---
|
||||
|
||||
## 参考文献
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的文献条目：
|
||||
|
||||
```bibtex
|
||||
@inproceedings{key2015,
|
||||
title = {Title of the Paper},
|
||||
author = {Author, A. and Author, B.},
|
||||
year = {2015}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：`mlsys.bib` 中不可出现重复的 key，添加前请先检索是否已存在。
|
||||
|
||||
正文引用示例：
|
||||
|
||||
```markdown
|
||||
这篇文章参考了论文 :cite:`cnn2015`。
|
||||
多篇文献引用：:cite:`cnn2015,rnn2015`。
|
||||
```
|
||||
@@ -99,14 +99,14 @@ sh build_mdbook_v2.sh
|
||||
# 中文版生成结果位于 .mdbook-v2-zh/book
|
||||
```
|
||||
|
||||
更多细节请参考 [构建指南](CONTRIBUTING/info.md)。
|
||||
更多细节请参考 [构建指南](CONTRIBUTING/info_zh.md)。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
我们欢迎任何形式的贡献，详细流程请参阅 **[贡献指南](CONTRIBUTING/CONTRIBUTING.md)**。
|
||||
我们欢迎任何形式的贡献，详细流程请参阅 **[贡献指南](CONTRIBUTING/CONTRIBUTING_zh.md)**。
|
||||
|
||||
提交前请阅读：
|
||||
- [写作样式规范](CONTRIBUTING/style.md)
|
||||
- [写作样式规范](CONTRIBUTING/style_zh.md)
|
||||
- [中英文术语对照](CONTRIBUTING/terminology.md)
|
||||
|
||||
## 社区
|
||||
|
||||
@@ -101,14 +101,14 @@ sh build_mdbook_v2.sh
|
||||
# Chinese output: .mdbook-v2-zh/book
|
||||
```
|
||||
|
||||
For more details, see the [Build Guide](CONTRIBUTING/info.md).
|
||||
For more details, see the [Build Guide](CONTRIBUTING/info_en.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](CONTRIBUTING/CONTRIBUTING.md)**.
|
||||
We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](CONTRIBUTING/CONTRIBUTING_en.md)**.
|
||||
|
||||
Before contributing, please read:
|
||||
- [Writing Style Guide](CONTRIBUTING/style.md)
|
||||
- [Writing Style Guide](CONTRIBUTING/style_en.md)
|
||||
- [Terminology Guide](CONTRIBUTING/terminology.md)
|
||||
|
||||
## Community
|
||||
|
||||
Reference in New Issue
Block a user