From d12d14a1eb44a783a66c7abbdc42d6abd6be72bd Mon Sep 17 00:00:00 2001 From: Yeqi Huang Date: Sun, 15 Mar 2026 18:07:53 +0000 Subject: [PATCH] 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 --------- Co-authored-by: Claude Opus 4.6 --- CONTRIBUTING/CONTRIBUTING.md | 253 ++++++++++++ .../Pic_Templates_and_Samples.pptx | Bin .../Requirements and Instructions.md | 0 CONTRIBUTING/info.md | 53 +++ CONTRIBUTING/issue.md | 19 + CONTRIBUTING/reference_guide.md | 38 ++ CONTRIBUTING/style.md | 365 ++++++++++++++++++ {v2/info => CONTRIBUTING}/terminology.md | 0 README.md | 8 +- README_EN.md | 8 +- build_mdbook_v1.sh | 4 +- build_mdbook_v2.sh | 4 +- tests/test_dark_mode_images_css.py | 8 +- v1/{ => config/en_config}/book.toml | 6 +- .../en_config}/theme/dark-mode-images.css | 0 .../zh => config/en_config}/theme/head.hbs | 0 .../en_config}/theme/version-selector.css | 0 .../en_config}/theme/version-selector.js | 0 v1/{books/zh => config/zh_config}/book.toml | 0 .../zh_config}/theme/dark-mode-images.css | 0 v1/{ => config/zh_config}/theme/head.hbs | 0 .../zh_config}/theme/version-selector.css | 0 .../zh_config}/theme/version-selector.js | 0 v2/{ => config/en_config}/book.toml | 6 +- .../en_config}/theme/dark-mode-images.css | 0 .../zh => config/en_config}/theme/head.hbs | 0 .../en_config}/theme/version-selector.css | 0 .../en_config}/theme/version-selector.js | 0 v2/{books/zh => config/zh_config}/book.toml | 0 .../zh_config}/theme/dark-mode-images.css | 0 v2/{ => config/zh_config}/theme/head.hbs | 0 .../zh_config}/theme/version-selector.css | 0 .../zh_config}/theme/version-selector.js | 0 v2/info/CONTRIBUTING.md | 123 ------ v2/info/CONTRIBUTING_zh.md | 123 ------ v2/info/info.md | 31 -- v2/info/issue.md | 12 - v2/info/refenence_guide.md | 30 -- v2/info/style.md | 173 --------- v2/info/style_zh.md | 173 --------- 40 files changed, 750 insertions(+), 687 deletions(-) create mode 100644 CONTRIBUTING/CONTRIBUTING.md rename {v2/info => CONTRIBUTING}/Pic-Instruction/Pic_Templates_and_Samples.pptx (100%) rename {v2/info => CONTRIBUTING}/Pic-Instruction/Requirements and Instructions.md (100%) create mode 100644 CONTRIBUTING/info.md create mode 100644 CONTRIBUTING/issue.md create mode 100644 CONTRIBUTING/reference_guide.md create mode 100644 CONTRIBUTING/style.md rename {v2/info => CONTRIBUTING}/terminology.md (100%) rename v1/{ => config/en_config}/book.toml (78%) rename v1/{ => config/en_config}/theme/dark-mode-images.css (100%) rename v1/{books/zh => config/en_config}/theme/head.hbs (100%) rename v1/{books/zh => config/en_config}/theme/version-selector.css (100%) rename v1/{books/zh => config/en_config}/theme/version-selector.js (100%) rename v1/{books/zh => config/zh_config}/book.toml (100%) rename v1/{books/zh => config/zh_config}/theme/dark-mode-images.css (100%) rename v1/{ => config/zh_config}/theme/head.hbs (100%) rename v1/{ => config/zh_config}/theme/version-selector.css (100%) rename v1/{ => config/zh_config}/theme/version-selector.js (100%) rename v2/{ => config/en_config}/book.toml (78%) rename v2/{ => config/en_config}/theme/dark-mode-images.css (100%) rename v2/{books/zh => config/en_config}/theme/head.hbs (100%) rename v2/{books/zh => config/en_config}/theme/version-selector.css (100%) rename v2/{books/zh => config/en_config}/theme/version-selector.js (100%) rename v2/{books/zh => config/zh_config}/book.toml (100%) rename v2/{books/zh => config/zh_config}/theme/dark-mode-images.css (100%) rename v2/{ => config/zh_config}/theme/head.hbs (100%) rename v2/{ => config/zh_config}/theme/version-selector.css (100%) rename v2/{ => config/zh_config}/theme/version-selector.js (100%) delete mode 100644 v2/info/CONTRIBUTING.md delete mode 100644 v2/info/CONTRIBUTING_zh.md delete mode 100644 v2/info/info.md delete mode 100644 v2/info/issue.md delete mode 100644 v2/info/refenence_guide.md delete mode 100644 v2/info/style.md delete mode 100644 v2/info/style_zh.md diff --git a/CONTRIBUTING/CONTRIBUTING.md b/CONTRIBUTING/CONTRIBUTING.md new file mode 100644 index 0000000..03075a8 --- /dev/null +++ b/CONTRIBUTING/CONTRIBUTING.md @@ -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_/` 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/` 目录。 diff --git a/v2/info/Pic-Instruction/Pic_Templates_and_Samples.pptx b/CONTRIBUTING/Pic-Instruction/Pic_Templates_and_Samples.pptx similarity index 100% rename from v2/info/Pic-Instruction/Pic_Templates_and_Samples.pptx rename to CONTRIBUTING/Pic-Instruction/Pic_Templates_and_Samples.pptx diff --git a/v2/info/Pic-Instruction/Requirements and Instructions.md b/CONTRIBUTING/Pic-Instruction/Requirements and Instructions.md similarity index 100% rename from v2/info/Pic-Instruction/Requirements and Instructions.md rename to CONTRIBUTING/Pic-Instruction/Requirements and Instructions.md diff --git a/CONTRIBUTING/info.md b/CONTRIBUTING/info.md new file mode 100644 index 0000000..055eebb --- /dev/null +++ b/CONTRIBUTING/info.md @@ -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)。 diff --git a/CONTRIBUTING/issue.md b/CONTRIBUTING/issue.md new file mode 100644 index 0000000..26bd62c --- /dev/null +++ b/CONTRIBUTING/issue.md @@ -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 diff --git a/CONTRIBUTING/reference_guide.md b/CONTRIBUTING/reference_guide.md new file mode 100644 index 0000000..b8441a6 --- /dev/null +++ b/CONTRIBUTING/reference_guide.md @@ -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` + ``` diff --git a/CONTRIBUTING/style.md b/CONTRIBUTING/style.md new file mode 100644 index 0000000..884dab8 --- /dev/null +++ b/CONTRIBUTING/style.md @@ -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/_chapter_/` 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 +![Figure description](../img/ch01/figure.png) +: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/`, 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/_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 +![图片描述](../img/ch01/figure.png) +: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`。 +``` diff --git a/v2/info/terminology.md b/CONTRIBUTING/terminology.md similarity index 100% rename from v2/info/terminology.md rename to CONTRIBUTING/terminology.md diff --git a/README.md b/README.md index 419ddb7..81844e3 100644 --- a/README.md +++ b/README.md @@ -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) ## 社区 diff --git a/README_EN.md b/README_EN.md index dc796c6..c96a0b1 100644 --- a/README_EN.md +++ b/README_EN.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 diff --git a/build_mdbook_v1.sh b/build_mdbook_v1.sh index 522f23b..4eda9a5 100755 --- a/build_mdbook_v1.sh +++ b/build_mdbook_v1.sh @@ -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 . diff --git a/build_mdbook_v2.sh b/build_mdbook_v2.sh index 4304c17..0fba175 100755 --- a/build_mdbook_v2.sh +++ b/build_mdbook_v2.sh @@ -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 . diff --git a/tests/test_dark_mode_images_css.py b/tests/test_dark_mode_images_css.py index 9027b16..db99a5d 100644 --- a/tests/test_dark_mode_images_css.py +++ b/tests/test_dark_mode_images_css.py @@ -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: diff --git a/v1/book.toml b/v1/config/en_config/book.toml similarity index 78% rename from v1/book.toml rename to v1/config/en_config/book.toml index aef487b..c99b562 100644 --- a/v1/book.toml +++ b/v1/config/en_config/book.toml @@ -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 diff --git a/v1/theme/dark-mode-images.css b/v1/config/en_config/theme/dark-mode-images.css similarity index 100% rename from v1/theme/dark-mode-images.css rename to v1/config/en_config/theme/dark-mode-images.css diff --git a/v1/books/zh/theme/head.hbs b/v1/config/en_config/theme/head.hbs similarity index 100% rename from v1/books/zh/theme/head.hbs rename to v1/config/en_config/theme/head.hbs diff --git a/v1/books/zh/theme/version-selector.css b/v1/config/en_config/theme/version-selector.css similarity index 100% rename from v1/books/zh/theme/version-selector.css rename to v1/config/en_config/theme/version-selector.css diff --git a/v1/books/zh/theme/version-selector.js b/v1/config/en_config/theme/version-selector.js similarity index 100% rename from v1/books/zh/theme/version-selector.js rename to v1/config/en_config/theme/version-selector.js diff --git a/v1/books/zh/book.toml b/v1/config/zh_config/book.toml similarity index 100% rename from v1/books/zh/book.toml rename to v1/config/zh_config/book.toml diff --git a/v1/books/zh/theme/dark-mode-images.css b/v1/config/zh_config/theme/dark-mode-images.css similarity index 100% rename from v1/books/zh/theme/dark-mode-images.css rename to v1/config/zh_config/theme/dark-mode-images.css diff --git a/v1/theme/head.hbs b/v1/config/zh_config/theme/head.hbs similarity index 100% rename from v1/theme/head.hbs rename to v1/config/zh_config/theme/head.hbs diff --git a/v1/theme/version-selector.css b/v1/config/zh_config/theme/version-selector.css similarity index 100% rename from v1/theme/version-selector.css rename to v1/config/zh_config/theme/version-selector.css diff --git a/v1/theme/version-selector.js b/v1/config/zh_config/theme/version-selector.js similarity index 100% rename from v1/theme/version-selector.js rename to v1/config/zh_config/theme/version-selector.js diff --git a/v2/book.toml b/v2/config/en_config/book.toml similarity index 78% rename from v2/book.toml rename to v2/config/en_config/book.toml index ea6bc17..3323307 100644 --- a/v2/book.toml +++ b/v2/config/en_config/book.toml @@ -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 diff --git a/v2/theme/dark-mode-images.css b/v2/config/en_config/theme/dark-mode-images.css similarity index 100% rename from v2/theme/dark-mode-images.css rename to v2/config/en_config/theme/dark-mode-images.css diff --git a/v2/books/zh/theme/head.hbs b/v2/config/en_config/theme/head.hbs similarity index 100% rename from v2/books/zh/theme/head.hbs rename to v2/config/en_config/theme/head.hbs diff --git a/v2/books/zh/theme/version-selector.css b/v2/config/en_config/theme/version-selector.css similarity index 100% rename from v2/books/zh/theme/version-selector.css rename to v2/config/en_config/theme/version-selector.css diff --git a/v2/books/zh/theme/version-selector.js b/v2/config/en_config/theme/version-selector.js similarity index 100% rename from v2/books/zh/theme/version-selector.js rename to v2/config/en_config/theme/version-selector.js diff --git a/v2/books/zh/book.toml b/v2/config/zh_config/book.toml similarity index 100% rename from v2/books/zh/book.toml rename to v2/config/zh_config/book.toml diff --git a/v2/books/zh/theme/dark-mode-images.css b/v2/config/zh_config/theme/dark-mode-images.css similarity index 100% rename from v2/books/zh/theme/dark-mode-images.css rename to v2/config/zh_config/theme/dark-mode-images.css diff --git a/v2/theme/head.hbs b/v2/config/zh_config/theme/head.hbs similarity index 100% rename from v2/theme/head.hbs rename to v2/config/zh_config/theme/head.hbs diff --git a/v2/theme/version-selector.css b/v2/config/zh_config/theme/version-selector.css similarity index 100% rename from v2/theme/version-selector.css rename to v2/config/zh_config/theme/version-selector.css diff --git a/v2/theme/version-selector.js b/v2/config/zh_config/theme/version-selector.js similarity index 100% rename from v2/theme/version-selector.js rename to v2/config/zh_config/theme/version-selector.js diff --git a/v2/info/CONTRIBUTING.md b/v2/info/CONTRIBUTING.md deleted file mode 100644 index ac7c2e2..0000000 --- a/v2/info/CONTRIBUTING.md +++ /dev/null @@ -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_/` 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. diff --git a/v2/info/CONTRIBUTING_zh.md b/v2/info/CONTRIBUTING_zh.md deleted file mode 100644 index ee54d1f..0000000 --- a/v2/info/CONTRIBUTING_zh.md +++ /dev/null @@ -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/` 目录。 diff --git a/v2/info/info.md b/v2/info/info.md deleted file mode 100644 index 34f4bf3..0000000 --- a/v2/info/info.md +++ /dev/null @@ -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)。 diff --git a/v2/info/issue.md b/v2/info/issue.md deleted file mode 100644 index 54a406c..0000000 --- a/v2/info/issue.md +++ /dev/null @@ -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 diff --git a/v2/info/refenence_guide.md b/v2/info/refenence_guide.md deleted file mode 100644 index 4977c23..0000000 --- a/v2/info/refenence_guide.md +++ /dev/null @@ -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` - ``` diff --git a/v2/info/style.md b/v2/info/style.md deleted file mode 100644 index 2fdce63..0000000 --- a/v2/info/style.md +++ /dev/null @@ -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/_chapter_/` 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 -![Figure description](../img/ch01/figure.png) -: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/`, 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`. -``` diff --git a/v2/info/style_zh.md b/v2/info/style_zh.md deleted file mode 100644 index c199625..0000000 --- a/v2/info/style_zh.md +++ /dev/null @@ -1,173 +0,0 @@ -# 写作样式规范 - -本文档规定了 v2 章节内容的写作格式与样式要求。所有贡献者在撰写或修改内容时请遵循以下规范。 - -> **注意：** LaTeX 转 Markdown 的工作流已**废弃**。v2 中所有内容直接使用 Markdown 书写，无需通过 Pandoc 等工具转换。 - ---- - -## 目录 - -- [文件结构](#文件结构) -- [自定义语法](#自定义语法) -- [图片规范](#图片规范) -- [表格规范](#表格规范) -- [代码块规范](#代码块规范) -- [参考文献](#参考文献) - ---- - -## 文件结构 - -- 每章对应 `v2/zh_chapters/_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 -![图片描述](../img/ch01/figure.png) -: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`。 -```