mirror of
https://github.com/openmlsys/openmlsys-zh.git
synced 2026-03-20 12:07:45 +08:00
refactor: symmetric config layout and root CONTRIBUTING docs (#502)
* refactor: reorganize mdbook config and contributing docs * fix: correct preprocessor relative paths in book.toml configs The preprocessor command paths had one extra ../ level, resolving outside the repo root. Fix from ../../../../tools/ to ../../../tools/. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yeqi Huang
253
CONTRIBUTING/CONTRIBUTING.md
Normal file
253
CONTRIBUTING/CONTRIBUTING.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Contributing Guide
|
||||
|
||||
> **Note:** The v1 version of this project has been archived (located in the `v1/` directory) and no longer accepts new contributions. Please submit all content contributions to v2 (the `v2/` directory).
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
openmlsys/
|
||||
├── v2/ # Version 2 (active version, accepting contributions)
|
||||
│ ├── zh_chapters/ # Chinese chapter source files
|
||||
│ │ ├── 00_chapter_preface/ # Per-chapter directory (numeric prefix + name)
|
||||
│ │ ├── 01_chapter_introduction/
|
||||
│ │ ├── ...
|
||||
│ │ ├── index.md # Book homepage
|
||||
│ │ └── SUMMARY.md # Auto-generated by script — do not edit manually
|
||||
│ ├── en_chapters/ # English chapter source files (same structure as zh_chapters)
|
||||
│ ├── config/
|
||||
│ │ ├── en_config/ # English mdBook configuration
|
||||
│ │ └── zh_config/ # Chinese mdBook configuration
|
||||
├── v1/ # Version 1 (archived)
|
||||
├── CONTRIBUTING/ # Contributing guides and documentation
|
||||
├── img/ # Shared image assets for the entire book
|
||||
├── references/ # Reference directory
|
||||
├── tools/ # Build and preprocessing scripts
|
||||
│ ├── prepare_mdbook.py # Core preprocessor: parses custom syntax, generates SUMMARY
|
||||
│ └── mdbook_preprocessor.py # mdBook preprocessor entry point
|
||||
└── build_mdbook_v2.sh # One-click build script for v2
|
||||
```
|
||||
|
||||
**Important**: `SUMMARY.md` is auto-generated by `tools/prepare_mdbook_zh.py` based on the `toc` block in `index.md`. **Do not edit it manually.**
|
||||
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
```bash
|
||||
# 1. Install Rust toolchain
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
# 2. Install mdBook
|
||||
cargo install mdbook
|
||||
|
||||
# 3. Clone the repository (Python 3 must also be installed)
|
||||
git clone https://github.com/openmlsys/openmlsys.git
|
||||
cd openmlsys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Local Build
|
||||
|
||||
### Build both Chinese and English versions of v2
|
||||
|
||||
```bash
|
||||
bash build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
Build output is placed in `.mdbook-v2-zh/book` (Chinese) and `.mdbook-v2/book` (English).
|
||||
|
||||
### Live Preview
|
||||
|
||||
```bash
|
||||
# Live preview — Chinese version
|
||||
cd v2/config/zh_config && mdbook serve --open
|
||||
# Live preview — English version
|
||||
cd v2/config/en_config && mdbook serve --open
|
||||
```
|
||||
|
||||
After modifying source files under `zh_chapters/` or `en_chapters/`, the browser will refresh automatically.
|
||||
|
||||
> **Note**: The preprocessing script regenerates `SUMMARY.md` on every build. If you encounter a build error, first check that the `toc` block format in `index.md` is correct.
|
||||
|
||||
---
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style.md)**.
|
||||
|
||||
---
|
||||
|
||||
## Submission Workflow
|
||||
|
||||
1. **Fork** this repository and create a feature branch:
|
||||
```bash
|
||||
git checkout -b feat/chapter-xxx-section-yyy
|
||||
```
|
||||
|
||||
2. **Validate locally**: After making changes, run `bash build_mdbook_v2.sh` and confirm there are no errors.
|
||||
|
||||
3. **Commit your changes**: Follow semantic commit message conventions:
|
||||
```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"
|
||||
```
|
||||
Common prefixes: `feat` (new content), `fix` (corrections), `refactor` (restructuring), `style` (formatting), `ci` (build pipeline updates)
|
||||
|
||||
4. **Open a Pull Request** targeting the `main` branch. Please use the provided PR templates:
|
||||
|
||||
- [Chinese PR template](.github/PULL_REQUEST_TEMPLATE/zh.md)
|
||||
- [English PR template](.github/PULL_REQUEST_TEMPLATE/en.md)
|
||||
|
||||
5. **Code review**: At least one contributor other than the author is required to review the PR. GitHub Actions will automatically verify that the new content builds successfully.
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: How do I add a new chapter?**
|
||||
|
||||
- Create a `chapter_<name>/` directory under `v2/zh_chapters/`
|
||||
- Create `index.md` and list the sections inside a `toc` block
|
||||
- Register the new chapter in the `toc` block of `v2/zh_chapters/index.md`
|
||||
- Ensure the local build passes before submitting a PR
|
||||
|
||||
**Q: How do I add a reference?**
|
||||
|
||||
Add a BibTeX entry to `mlsys.bib`, then cite it in the body text using `:cite:`key``.
|
||||
|
||||
**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/` 目录。
|
||||
53
CONTRIBUTING/info.md
Normal file
53
CONTRIBUTING/info.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# 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)。
|
||||
19
CONTRIBUTING/issue.md
Normal file
19
CONTRIBUTING/issue.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# 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
|
||||
38
CONTRIBUTING/reference_guide.md
Normal file
38
CONTRIBUTING/reference_guide.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# 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`
|
||||
```
|
||||
365
CONTRIBUTING/style.md
Normal file
365
CONTRIBUTING/style.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Writing Style Guide
|
||||
|
||||
This document defines the formatting and style requirements for v2 chapter content. All contributors must follow these guidelines when writing or modifying content.
|
||||
|
||||
> **Note:** The LaTeX-to-Markdown conversion workflow has been **deprecated**. All v2 content is written directly in Markdown — no Pandoc or similar tools are needed.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [File Structure](#file-structure)
|
||||
- [Custom Syntax](#custom-syntax)
|
||||
- [Figure Guidelines](#figure-guidelines)
|
||||
- [Table Guidelines](#table-guidelines)
|
||||
- [Code Block Guidelines](#code-block-guidelines)
|
||||
- [References](#references)
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- Each chapter corresponds to a `v2/en_chapters/<nn>_chapter_<name>/` directory (e.g., `02_chapter_programming_and_graph/`)
|
||||
- The chapter entry file is `index.md`; section content goes in separate `.md` files in the same directory
|
||||
- Declare the section structure in `index.md` using a `toc` block (used to auto-generate `SUMMARY.md`):
|
||||
|
||||
```markdown
|
||||
```toc
|
||||
:maxdepth: 2
|
||||
|
||||
section_one
|
||||
section_two
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Syntax
|
||||
|
||||
The project preprocessor supports the following extended Markdown syntax. **Follow it strictly** to ensure a correct build.
|
||||
|
||||
### Inline Math
|
||||
|
||||
```markdown
|
||||
The model learns the mapping $f: \mathcal{X} \rightarrow \mathcal{Y}$.
|
||||
```
|
||||
|
||||
### Display Math with Label
|
||||
|
||||
Label names should include a language suffix (e.g., `-en`) to avoid conflicts with Chinese labels:
|
||||
|
||||
```markdown
|
||||
$$
|
||||
\mathcal{L}_{CE} = -\sum_{i=1}^{N} y_i \log(\hat{y}_i)
|
||||
$$
|
||||
:eqlabel:`eq-cross-entropy-en`
|
||||
```
|
||||
|
||||
Reference an equation: `:eqref:`eq-cross-entropy-en``
|
||||
|
||||
### Figures with Labels
|
||||
|
||||
```markdown
|
||||
|
||||
:width:`600px`
|
||||
:label:`figure-label-en`
|
||||
```
|
||||
|
||||
Reference a figure: `:numref:`figure-label-en``
|
||||
|
||||
### Section References
|
||||
|
||||
Add a label after a section heading:
|
||||
|
||||
```markdown
|
||||
### Section Title
|
||||
:label:`my-section-en`
|
||||
```
|
||||
|
||||
Reference the section: `:ref:`my-section-en``
|
||||
|
||||
### Citations
|
||||
|
||||
```markdown
|
||||
The perceptron :cite:`rosenblatt1958perceptron` is one of the earliest neural network models.
|
||||
```
|
||||
|
||||
Multiple citations separated by commas: `:cite:`paper1,paper2``
|
||||
|
||||
All bibliography entries are maintained in `mlsys.bib` (see [References](#references)).
|
||||
|
||||
---
|
||||
|
||||
## Figure Guidelines
|
||||
|
||||
### Storage Location
|
||||
|
||||
Store figures under `img/ch<chapter-number>/`, e.g., `img/ch01/`. Image files must be committed together with the PR.
|
||||
|
||||
### Naming
|
||||
|
||||
Use lowercase English with hyphens, e.g., `framework-architecture.png`.
|
||||
|
||||
### Format
|
||||
|
||||
| Format | Use case |
|
||||
|--------|---------|
|
||||
| SVG | Hand-drawn diagrams and flowcharts (vector, lossless scaling); remove white background |
|
||||
| PNG | Screenshots, photos, or images with complex gradients |
|
||||
|
||||
Recommended tools:
|
||||
|
||||
- **[Excalidraw MCP](https://github.com/excalidraw/excalidraw-mcp)** — Official Excalidraw MCP server for AI-assisted diagram creation (remote: `https://mcp.excalidraw.com`)
|
||||
- **[interactive-drawer](https://github.com/anyin233/interactive-drawer)** — Self-hosted Excalidraw MCP with session management
|
||||
- **PPT** — PowerPoint, see [Pic-Instruction/](Pic-Instruction/) for templates
|
||||
- **draw.io** — Free online diagramming tool
|
||||
|
||||
**Do not use images from the internet** (copyright risk).
|
||||
|
||||
### Resolution and Size
|
||||
|
||||
- Recommended resolution: ≥ 150 dpi
|
||||
- Maximum width: 1200 px
|
||||
- Set display width in Markdown via `:width:` (600–800 px recommended)
|
||||
|
||||
### Layout
|
||||
|
||||
Include sufficient explanatory text between adjacent figures. Do not place figures immediately next to each other.
|
||||
|
||||
---
|
||||
|
||||
## Table Guidelines
|
||||
|
||||
Use standard Markdown table syntax. Add a label to any table that needs to be referenced:
|
||||
|
||||
```markdown
|
||||
| Column 1 | Column 2 | Column 3 |
|
||||
|----------|----------|----------|
|
||||
| Value 1 | Value 2 | Value 3 |
|
||||
:label:`table-label-en`
|
||||
```
|
||||
|
||||
Reference a table: `:numref:`table-label-en``
|
||||
|
||||
---
|
||||
|
||||
## Code Block Guidelines
|
||||
|
||||
Use standard Markdown fenced code blocks and always specify the language:
|
||||
|
||||
````markdown
|
||||
```python
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
```
|
||||
````
|
||||
|
||||
Common language identifiers: `python`, `bash`, `cpp`, `markdown`, `text`.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
Add BibTeX entries to `mlsys.bib`:
|
||||
|
||||
```bibtex
|
||||
@inproceedings{key2015,
|
||||
title = {Title of the Paper},
|
||||
author = {Author, A. and Author, B.},
|
||||
year = {2015}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Duplicate keys in `mlsys.bib` are not allowed. Search for existing entries before adding a new one.
|
||||
|
||||
Example citations in body text:
|
||||
|
||||
```markdown
|
||||
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`。
|
||||
```
|
||||
@@ -99,15 +99,15 @@ sh build_mdbook_v2.sh
|
||||
# 中文版生成结果位于 .mdbook-v2-zh/book
|
||||
```
|
||||
|
||||
更多细节请参考 [构建指南](v2/info/info.md)。
|
||||
更多细节请参考 [构建指南](CONTRIBUTING/info.md)。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
我们欢迎任何形式的贡献，详细流程请参阅 **[贡献指南](v2/info/CONTRIBUTING_zh.md)**。
|
||||
我们欢迎任何形式的贡献，详细流程请参阅 **[贡献指南](CONTRIBUTING/CONTRIBUTING.md)**。
|
||||
|
||||
提交前请阅读：
|
||||
- [写作样式规范](v2/info/style_zh.md)
|
||||
- [中英文术语对照](v2/info/terminology.md)
|
||||
- [写作样式规范](CONTRIBUTING/style.md)
|
||||
- [中英文术语对照](CONTRIBUTING/terminology.md)
|
||||
|
||||
## 社区
|
||||
|
||||
|
||||
@@ -101,15 +101,15 @@ sh build_mdbook_v2.sh
|
||||
# Chinese output: .mdbook-v2-zh/book
|
||||
```
|
||||
|
||||
For more details, see the [Build Guide](v2/info/info.md).
|
||||
For more details, see the [Build Guide](CONTRIBUTING/info.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](v2/info/CONTRIBUTING.md)**.
|
||||
We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](CONTRIBUTING/CONTRIBUTING.md)**.
|
||||
|
||||
Before contributing, please read:
|
||||
- [Writing Style Guide](v2/info/style.md)
|
||||
- [Terminology Guide](v2/info/terminology.md)
|
||||
- [Writing Style Guide](CONTRIBUTING/style.md)
|
||||
- [Terminology Guide](CONTRIBUTING/terminology.md)
|
||||
|
||||
## Community
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ fi
|
||||
--summary-output "${ROOT}/v1/en_chapters/SUMMARY.md" \
|
||||
--placeholder-prefix "[TODO: src = zh_chapters/"
|
||||
|
||||
cd "${ROOT}/v1" && mdbook build .
|
||||
cd "${ROOT}/v1/config/en_config" && mdbook build .
|
||||
|
||||
# ── Chinese v1 ────────────────────────────────────────────────────────────────
|
||||
"${PYTHON_BIN}" "${ROOT}/tools/ensure_book_resources.py" --chapter-dir "${ROOT}/v1/zh_chapters"
|
||||
@@ -29,4 +29,4 @@ cd "${ROOT}/v1" && mdbook build .
|
||||
--source "${ROOT}/v1/zh_chapters" \
|
||||
--summary-output "${ROOT}/v1/zh_chapters/SUMMARY.md"
|
||||
|
||||
cd "${ROOT}/v1/books/zh" && mdbook build .
|
||||
cd "${ROOT}/v1/config/zh_config" && mdbook build .
|
||||
|
||||
@@ -21,7 +21,7 @@ fi
|
||||
--summary-output "${ROOT}/v2/en_chapters/SUMMARY.md" \
|
||||
--placeholder-prefix "[TODO: src = zh_chapters/"
|
||||
|
||||
cd "${ROOT}/v2" && mdbook build .
|
||||
cd "${ROOT}/v2/config/en_config" && mdbook build .
|
||||
|
||||
# ── Chinese v2 ────────────────────────────────────────────────────────────────
|
||||
"${PYTHON_BIN}" "${ROOT}/tools/ensure_book_resources.py" --chapter-dir "${ROOT}/v2/zh_chapters"
|
||||
@@ -29,4 +29,4 @@ cd "${ROOT}/v2" && mdbook build .
|
||||
--source "${ROOT}/v2/zh_chapters" \
|
||||
--summary-output "${ROOT}/v2/zh_chapters/SUMMARY.md"
|
||||
|
||||
cd "${ROOT}/v2/books/zh" && mdbook build .
|
||||
cd "${ROOT}/v2/config/zh_config" && mdbook build .
|
||||
|
||||
@@ -10,10 +10,10 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
class DarkModeImagesCssTests(unittest.TestCase):
|
||||
def test_both_theme_css_files_style_dark_mode_body_images_only(self) -> None:
|
||||
css_paths = [
|
||||
REPO_ROOT / "v1" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v1" / "books" / "zh" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v2" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v2" / "books" / "zh" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v1" / "config" / "en_config" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v1" / "config" / "zh_config" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v2" / "config" / "en_config" / "theme" / "dark-mode-images.css",
|
||||
REPO_ROOT / "v2" / "config" / "zh_config" / "theme" / "dark-mode-images.css",
|
||||
]
|
||||
|
||||
for css_path in css_paths:
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
[book]
|
||||
authors = ["OpenMLSys Contributors"]
|
||||
language = "en"
|
||||
src = "en_chapters"
|
||||
src = "../../en_chapters"
|
||||
title = "Machine Learning Systems: Design and Implementation (1st Edition)"
|
||||
|
||||
[build]
|
||||
build-dir = "../.mdbook-v1/book"
|
||||
build-dir = "../../../.mdbook-v1/book"
|
||||
create-missing = false
|
||||
|
||||
[preprocessor.openmlsys]
|
||||
command = "python3 ../tools/mdbook_preprocessor.py"
|
||||
command = "python3 ../../../tools/mdbook_preprocessor.py"
|
||||
|
||||
[output.html]
|
||||
mathjax-support = true
|
||||
@@ -1,15 +1,15 @@
|
||||
[book]
|
||||
authors = ["OpenMLSys Contributors"]
|
||||
language = "en"
|
||||
src = "en_chapters"
|
||||
src = "../../en_chapters"
|
||||
title = "Machine Learning Systems: Design and Implementation (2nd Edition)"
|
||||
|
||||
[build]
|
||||
build-dir = "../.mdbook-v2/book"
|
||||
build-dir = "../../../.mdbook-v2/book"
|
||||
create-missing = false
|
||||
|
||||
[preprocessor.openmlsys]
|
||||
command = "python3 ../tools/mdbook_preprocessor.py"
|
||||
command = "python3 ../../../tools/mdbook_preprocessor.py"
|
||||
|
||||
[output.html]
|
||||
mathjax-support = true
|
||||
@@ -1,123 +0,0 @@
|
||||
# Contributing Guide
|
||||
|
||||
> **Note:** The v1 version of this project has been archived (located in the `v1/` directory) and no longer accepts new contributions. Please submit all content contributions to v2 (the `v2/` directory).
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
openmlsys/
|
||||
├── v2/ # Version 2 (active version, accepting contributions)
|
||||
│ ├── zh_chapters/ # Chinese chapter source files
|
||||
│ │ ├── 00_chapter_preface/ # Per-chapter directory (numeric prefix + name)
|
||||
│ │ ├── 01_chapter_introduction/
|
||||
│ │ ├── ...
|
||||
│ │ ├── index.md # Book homepage
|
||||
│ │ └── SUMMARY.md # Auto-generated by script — do not edit manually
|
||||
│ ├── en_chapters/ # English chapter source files (same structure as zh_chapters)
|
||||
│ ├── books/zh/ # Chinese mdBook configuration (used for build)
|
||||
│ ├── info/ # Documentation (location of this file)
|
||||
│ └── book.toml # English mdBook configuration
|
||||
├── v1/ # Version 1 (archived)
|
||||
├── img/ # Shared image assets for the entire book
|
||||
├── references/ # Reference directory
|
||||
├── tools/ # Build and preprocessing scripts
|
||||
│ ├── prepare_mdbook.py # Core preprocessor: parses custom syntax, generates SUMMARY
|
||||
│ └── mdbook_preprocessor.py # mdBook preprocessor entry point
|
||||
└── build_mdbook_v2.sh # One-click build script for v2
|
||||
```
|
||||
|
||||
**Important**: `SUMMARY.md` is auto-generated by `tools/prepare_mdbook_zh.py` based on the `toc` block in `index.md`. **Do not edit it manually.**
|
||||
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
```bash
|
||||
# 1. Install Rust toolchain
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
# 2. Install mdBook
|
||||
cargo install mdbook
|
||||
|
||||
# 3. Clone the repository (Python 3 must also be installed)
|
||||
git clone https://github.com/openmlsys/openmlsys.git
|
||||
cd openmlsys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Local Build
|
||||
|
||||
### Build both Chinese and English versions of v2
|
||||
|
||||
```bash
|
||||
bash build_mdbook_v2.sh
|
||||
```
|
||||
|
||||
Build output is placed in `.mdbook-v2-zh/book` (Chinese) and `.mdbook-v2/book` (English).
|
||||
|
||||
### Live Preview
|
||||
|
||||
```bash
|
||||
# Live preview — Chinese version
|
||||
cd v2/books/zh && mdbook serve --open
|
||||
# Live preview — English version
|
||||
cd v2/ && mdbook serve --open
|
||||
```
|
||||
|
||||
After modifying source files under `zh_chapters/` or `en_chapters/`, the browser will refresh automatically.
|
||||
|
||||
> **Note**: The preprocessing script regenerates `SUMMARY.md` on every build. If you encounter a build error, first check that the `toc` block format in `index.md` is correct.
|
||||
|
||||
---
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style.md)**.
|
||||
|
||||
---
|
||||
|
||||
## Submission Workflow
|
||||
|
||||
1. **Fork** this repository and create a feature branch:
|
||||
```bash
|
||||
git checkout -b feat/chapter-xxx-section-yyy
|
||||
```
|
||||
|
||||
2. **Validate locally**: After making changes, run `bash build_mdbook_v2.sh` and confirm there are no errors.
|
||||
|
||||
3. **Commit your changes**: Follow semantic commit message conventions:
|
||||
```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"
|
||||
```
|
||||
Common prefixes: `feat` (new content), `fix` (corrections), `refactor` (restructuring), `style` (formatting), `ci` (build pipeline updates)
|
||||
|
||||
4. **Open a Pull Request** targeting the `main` branch. Please use the provided PR templates:
|
||||
|
||||
- [Chinese PR template](.github/PULL_REQUEST_TEMPLATE/zh.md)
|
||||
- [English PR template](.github/PULL_REQUEST_TEMPLATE/en.md)
|
||||
|
||||
5. **Code review**: At least one contributor other than the author is required to review the PR. GitHub Actions will automatically verify that the new content builds successfully.
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: How do I add a new chapter?**
|
||||
|
||||
- Create a `chapter_<name>/` directory under `v2/zh_chapters/`
|
||||
- Create `index.md` and list the sections inside a `toc` block
|
||||
- Register the new chapter in the `toc` block of `v2/zh_chapters/index.md`
|
||||
- Ensure the local build passes before submitting a PR
|
||||
|
||||
**Q: How do I add a reference?**
|
||||
|
||||
Add a BibTeX entry to `mlsys.bib`, then cite it in the body text using `:cite:\`key\``.
|
||||
|
||||
**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.
|
||||
@@ -1,123 +0,0 @@
|
||||
# 贡献指南
|
||||
|
||||
> **注意：** 本项目的 v1 版本已归档（位于 `v1/` 目录），不再接受新的贡献。请将所有内容贡献提交至 v2（`v2/` 目录）。
|
||||
|
||||
---
|
||||
|
||||
## 仓库结构说明
|
||||
|
||||
```
|
||||
openmlsys/
|
||||
├── v2/ # 第二版（当前活跃版本，接受贡献）
|
||||
│ ├── zh_chapters/ # 中文章节源文件
|
||||
│ │ ├── 00_chapter_preface/ # 各章目录（数字前缀 + 名称）
|
||||
│ │ ├── 01_chapter_introduction/
|
||||
│ │ ├── ...
|
||||
│ │ ├── index.md # 全书首页
|
||||
│ │ └── SUMMARY.md # 由脚本自动生成，勿手动编辑
|
||||
│ ├── en_chapters/ # 英文章节源文件（结构与中文章节一致）
|
||||
│ ├── books/zh/ # 中文 mdBook 配置（供构建使用）
|
||||
│ ├── info/ # 文档（本文件所在位置）
|
||||
│ └── book.toml # 英文版 mdBook 配置
|
||||
├── v1/ # 第一版（已归档）
|
||||
├── 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/books/zh && mdbook serve --open
|
||||
# 英文版实时预览
|
||||
cd v2/ && 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,31 +0,0 @@
|
||||
## 环境安装
|
||||
机器学习系统书籍部署在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_mdbook_v2.sh脚本进行编译，保证首页正确合并到书籍中去。
|
||||
```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.md)。
|
||||
|
||||
## 中英文术语对照
|
||||
|
||||
翻译请参照[中英文术语对照](terminology.md)。
|
||||
@@ -1,12 +0,0 @@
|
||||
# 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,30 +0,0 @@
|
||||
# 参考文献引用方式
|
||||
|
||||
所有参考文献统一维护在 `mlsys.bib` 中。
|
||||
|
||||
## 添加文献条目
|
||||
|
||||
在 `mlsys.bib` 中添加 BibTeX 格式的条目，添加前请先检索是否已存在同名 key：
|
||||
|
||||
```bibtex
|
||||
@inproceedings{cnn2015,
|
||||
title = {CNN},
|
||||
author = {xxx},
|
||||
year = {2015},
|
||||
keywords = {xxx}
|
||||
}
|
||||
```
|
||||
|
||||
## 正文引用
|
||||
|
||||
引用时前面需要有一个空格：
|
||||
|
||||
1. 单篇参考文献
|
||||
```
|
||||
这篇文章参考了论文 :cite:`cnn2015`
|
||||
```
|
||||
|
||||
2. 多篇参考文献用逗号分隔
|
||||
```
|
||||
这篇文章参考了论文 :cite:`cnn2015,rnn2015`
|
||||
```
|
||||
173
v2/info/style.md
173
v2/info/style.md
@@ -1,173 +0,0 @@
|
||||
# Writing Style Guide
|
||||
|
||||
This document defines the formatting and style requirements for v2 chapter content. All contributors must follow these guidelines when writing or modifying content.
|
||||
|
||||
> **Note:** The LaTeX-to-Markdown conversion workflow has been **deprecated**. All v2 content is written directly in Markdown — no Pandoc or similar tools are needed.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [File Structure](#file-structure)
|
||||
- [Custom Syntax](#custom-syntax)
|
||||
- [Figure Guidelines](#figure-guidelines)
|
||||
- [Table Guidelines](#table-guidelines)
|
||||
- [Code Block Guidelines](#code-block-guidelines)
|
||||
- [References](#references)
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- Each chapter corresponds to a `v2/en_chapters/<nn>_chapter_<name>/` directory (e.g., `02_chapter_programming_and_graph/`)
|
||||
- The chapter entry file is `index.md`; section content goes in separate `.md` files in the same directory
|
||||
- Declare the section structure in `index.md` using a `toc` block (used to auto-generate `SUMMARY.md`):
|
||||
|
||||
```markdown
|
||||
```toc
|
||||
:maxdepth: 2
|
||||
|
||||
section_one
|
||||
section_two
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Syntax
|
||||
|
||||
The project preprocessor supports the following extended Markdown syntax. **Follow it strictly** to ensure a correct build.
|
||||
|
||||
### Inline Math
|
||||
|
||||
```markdown
|
||||
The model learns the mapping $f: \mathcal{X} \rightarrow \mathcal{Y}$.
|
||||
```
|
||||
|
||||
### Display Math with Label
|
||||
|
||||
Label names should include a language suffix (e.g., `-en`) to avoid conflicts with Chinese labels:
|
||||
|
||||
```markdown
|
||||
$$
|
||||
\mathcal{L}_{CE} = -\sum_{i=1}^{N} y_i \log(\hat{y}_i)
|
||||
$$
|
||||
:eqlabel:`eq-cross-entropy-en`
|
||||
```
|
||||
|
||||
Reference an equation: `:eqref:\`eq-cross-entropy-en\``
|
||||
|
||||
### Figures with Labels
|
||||
|
||||
```markdown
|
||||
|
||||
:width:`600px`
|
||||
:label:`figure-label-en`
|
||||
```
|
||||
|
||||
Reference a figure: `:numref:\`figure-label-en\``
|
||||
|
||||
### Section References
|
||||
|
||||
Add a label after a section heading:
|
||||
|
||||
```markdown
|
||||
### Section Title
|
||||
:label:`my-section-en`
|
||||
```
|
||||
|
||||
Reference the section: `:ref:\`my-section-en\``
|
||||
|
||||
### Citations
|
||||
|
||||
```markdown
|
||||
The perceptron :cite:`rosenblatt1958perceptron` is one of the earliest neural network models.
|
||||
```
|
||||
|
||||
Multiple citations separated by commas: `:cite:\`paper1,paper2\``
|
||||
|
||||
All bibliography entries are maintained in `mlsys.bib` (see [References](#references)).
|
||||
|
||||
---
|
||||
|
||||
## Figure Guidelines
|
||||
|
||||
### Storage Location
|
||||
|
||||
Store figures under `img/ch<chapter-number>/`, e.g., `img/ch01/`. Image files must be committed together with the PR.
|
||||
|
||||
### Naming
|
||||
|
||||
Use lowercase English with hyphens, e.g., `framework-architecture.png`.
|
||||
|
||||
### Format
|
||||
|
||||
| Format | Use case |
|
||||
|--------|---------|
|
||||
| SVG | Hand-drawn diagrams and flowcharts (vector, lossless scaling); remove white background |
|
||||
| PNG | Screenshots, photos, or images with complex gradients |
|
||||
|
||||
Recommended tools: PPT, draw.io. **Do not use images from the internet** (copyright risk).
|
||||
|
||||
### Resolution and Size
|
||||
|
||||
- Recommended resolution: ≥ 150 dpi
|
||||
- Maximum width: 1200 px
|
||||
- Set display width in Markdown via `:width:` (600–800 px recommended)
|
||||
|
||||
### Layout
|
||||
|
||||
Include sufficient explanatory text between adjacent figures. Do not place figures immediately next to each other.
|
||||
|
||||
---
|
||||
|
||||
## Table Guidelines
|
||||
|
||||
Use standard Markdown table syntax. Add a label to any table that needs to be referenced:
|
||||
|
||||
```markdown
|
||||
| Column 1 | Column 2 | Column 3 |
|
||||
|----------|----------|----------|
|
||||
| Value 1 | Value 2 | Value 3 |
|
||||
:label:`table-label-en`
|
||||
```
|
||||
|
||||
Reference a table: `:numref:\`table-label-en\``
|
||||
|
||||
---
|
||||
|
||||
## Code Block Guidelines
|
||||
|
||||
Use standard Markdown fenced code blocks and always specify the language:
|
||||
|
||||
````markdown
|
||||
```python
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
```
|
||||
````
|
||||
|
||||
Common language identifiers: `python`, `bash`, `cpp`, `markdown`, `text`.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
Add BibTeX entries to `mlsys.bib`:
|
||||
|
||||
```bibtex
|
||||
@inproceedings{key2015,
|
||||
title = {Title of the Paper},
|
||||
author = {Author, A. and Author, B.},
|
||||
year = {2015}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Duplicate keys in `mlsys.bib` are not allowed. Search for existing entries before adding a new one.
|
||||
|
||||
Example citations in body text:
|
||||
|
||||
```markdown
|
||||
This chapter references the paper :cite:`cnn2015`.
|
||||
Multiple citations: :cite:`cnn2015,rnn2015`.
|
||||
```
|
||||
@@ -1,173 +0,0 @@
|
||||
# 写作样式规范
|
||||
|
||||
本文档规定了 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 | 截图、照片、含复杂渐变的图片 |
|
||||
|
||||
推荐使用 PPT、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`。
|
||||
```
|
||||
Reference in New Issue
Block a user