diff --git a/CONTRIBUTING/CONTRIBUTING.md b/CONTRIBUTING/CONTRIBUTING_en.md similarity index 51% rename from CONTRIBUTING/CONTRIBUTING.md rename to CONTRIBUTING/CONTRIBUTING_en.md index 03075a8..df84fa9 100644 --- a/CONTRIBUTING/CONTRIBUTING.md +++ b/CONTRIBUTING/CONTRIBUTING_en.md @@ -76,7 +76,7 @@ After modifying source files under `zh_chapters/` or `en_chapters/`, the browser ## Writing Guidelines -For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style.md)**. +For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the **[Writing Style Guide](style_en.md)**. --- @@ -122,132 +122,3 @@ Add a BibTeX entry to `mlsys.bib`, then cite it in the body text using `:cite:`k **Q: The build says it cannot find an image — what should I do?** Check that the image path starts with `../img/` (relative to the chapter directory) and that the image file has been committed to the `img/` directory. - ---- - ---- - -# 贡献指南 - -> **注意:** 本项目的 v1 版本已归档(位于 `v1/` 目录),不再接受新的贡献。请将所有内容贡献提交至 v2(`v2/` 目录)。 - ---- - -## 仓库结构说明 - -``` -openmlsys/ -├── v2/ # 第二版(当前活跃版本,接受贡献) -│ ├── zh_chapters/ # 中文章节源文件 -│ │ ├── 00_chapter_preface/ # 各章目录(数字前缀 + 名称) -│ │ ├── 01_chapter_introduction/ -│ │ ├── ... -│ │ ├── index.md # 全书首页 -│ │ └── SUMMARY.md # 由脚本自动生成,勿手动编辑 -│ ├── en_chapters/ # 英文章节源文件(结构与中文章节一致) -│ ├── config/ -│ │ ├── en_config/ # 英文版 mdBook 配置 -│ │ └── zh_config/ # 中文版 mdBook 配置 -├── v1/ # 第一版(已归档) -├── CONTRIBUTING/ # 贡献指南与相关文档 -├── img/ # 全书共享图片资源 -├── references/ # 参考文献目录 -├── tools/ # 构建与预处理脚本 -│ ├── prepare_mdbook.py # 核心预处理:解析自定义语法、生成 SUMMARY -│ └── mdbook_preprocessor.py # mdBook 预处理器入口 -└── build_mdbook_v2.sh # v2 一键构建脚本 -``` - -**重要**:`SUMMARY.md` 由 `tools/prepare_mdbook_zh.py` 根据 `index.md` 中的 `toc` 块自动生成,**请勿手动修改**。 - ---- - -## 环境准备 - -```bash -# 1. 安装 Rust 工具链 -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - -# 2. 安装 mdBook -cargo install mdbook - -# 3. 克隆仓库(需预先安装 Python 3) -git clone https://github.com/openmlsys/openmlsys.git -cd openmlsys -``` - ---- - -## 本地构建 - -### 构建 v2 中英文双版本 - -```bash -bash build_mdbook_v2.sh -``` - -构建产物输出至 `.mdbook-v2-zh/book`(中文)和 `.mdbook-v2/book`(英文)。 - -### 实时预览 - -```bash -# 中文版实时预览 -cd v2/config/zh_config && mdbook serve --open -# 英文版实时预览 -cd v2/config/en_config && mdbook serve --open -``` - -修改 `zh_chapters/` 或 `en_chapters/` 下的源文件后,浏览器将自动刷新。 - -> **注意**:预处理脚本会在每次构建时重新生成 `SUMMARY.md`,如遇构建报错请先检查 `index.md` 中 `toc` 块的格式是否正确。 - ---- - -## 写作规范 - -详细的自定义语法(公式、图片标签、文献引用、代码块等)及图片规范,请参阅 **[写作样式规范](style.md)**。 - ---- - -## 提交流程 - -1. **Fork** 本仓库并创建功能分支: - ```bash - git checkout -b feat/chapter-xxx-section-yyy - ``` - -2. **本地构建验证**:修改完成后运行 `bash build_mdbook_v2.sh`,确保无报错 - -3. **提交代码**:遵循语义化提交信息 - ```bash - git commit -m "feat(zh): 新增第X章第Y节内容" - git commit -m "feat(en): Add content for chapter X section Y" - git commit -m "ci: update main.yml" - ``` - 常用前缀:`feat`(新内容)、`fix`(修正错误)、`refactor`(重组结构)、`style`(格式调整)、`ci`(构建流程更新) - -4. **发起 Pull Request**:目标分支为 `main`,请使用 PR 模板: - - - [中文 PR 模板](.github/PULL_REQUEST_TEMPLATE/zh.md) - - [英文 PR 模板](.github/PULL_REQUEST_TEMPLATE/en.md) - -5. **代码审查**:PR要求至少有一位非本人Contributor进行检查,且github action将会自动验证新增内容是否可以编译通过 - ---- - -## 常见问题 - -**Q:如何添加新章节?** - -- 在 `v2/zh_chapters/` 下新建 `chapter_<名称>/` 目录 -- 创建 `index.md`,在其中使用 `toc` 块列出各节 -- 在全书 `v2/zh_chapters/index.md` 的 `toc` 块中注册新章节 -- 确保本地构建通过后再提交 PR - -**Q:参考文献如何添加?** - -在 `mlsys.bib` 中添加 BibTeX 格式的文献条目,然后在正文中使用 `:cite:`key`` 引用。 - -**Q:构建时提示找不到图片怎么处理?** - -检查图片路径是否以 `../img/` 开头(相对于章节目录),以及图片文件是否已提交至 `img/` 目录。 diff --git a/CONTRIBUTING/CONTRIBUTING_zh.md b/CONTRIBUTING/CONTRIBUTING_zh.md new file mode 100644 index 0000000..acee9de --- /dev/null +++ b/CONTRIBUTING/CONTRIBUTING_zh.md @@ -0,0 +1,124 @@ +# 贡献指南 + +> **注意:** 本项目的 v1 版本已归档(位于 `v1/` 目录),不再接受新的贡献。请将所有内容贡献提交至 v2(`v2/` 目录)。 + +--- + +## 仓库结构说明 + +``` +openmlsys/ +├── v2/ # 第二版(当前活跃版本,接受贡献) +│ ├── zh_chapters/ # 中文章节源文件 +│ │ ├── 00_chapter_preface/ # 各章目录(数字前缀 + 名称) +│ │ ├── 01_chapter_introduction/ +│ │ ├── ... +│ │ ├── index.md # 全书首页 +│ │ └── SUMMARY.md # 由脚本自动生成,勿手动编辑 +│ ├── en_chapters/ # 英文章节源文件(结构与中文章节一致) +│ ├── config/ +│ │ ├── en_config/ # 英文版 mdBook 配置 +│ │ └── zh_config/ # 中文版 mdBook 配置 +├── v1/ # 第一版(已归档) +├── CONTRIBUTING/ # 贡献指南与相关文档 +├── img/ # 全书共享图片资源 +├── references/ # 参考文献目录 +├── tools/ # 构建与预处理脚本 +│ ├── prepare_mdbook.py # 核心预处理:解析自定义语法、生成 SUMMARY +│ └── mdbook_preprocessor.py # mdBook 预处理器入口 +└── build_mdbook_v2.sh # v2 一键构建脚本 +``` + +**重要**:`SUMMARY.md` 由 `tools/prepare_mdbook_zh.py` 根据 `index.md` 中的 `toc` 块自动生成,**请勿手动修改**。 + +--- + +## 环境准备 + +```bash +# 1. 安装 Rust 工具链 +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# 2. 安装 mdBook +cargo install mdbook + +# 3. 克隆仓库(需预先安装 Python 3) +git clone https://github.com/openmlsys/openmlsys.git +cd openmlsys +``` + +--- + +## 本地构建 + +### 构建 v2 中英文双版本 + +```bash +bash build_mdbook_v2.sh +``` + +构建产物输出至 `.mdbook-v2-zh/book`(中文)和 `.mdbook-v2/book`(英文)。 + +### 实时预览 + +```bash +# 中文版实时预览 +cd v2/config/zh_config && mdbook serve --open +# 英文版实时预览 +cd v2/config/en_config && mdbook serve --open +``` + +修改 `zh_chapters/` 或 `en_chapters/` 下的源文件后,浏览器将自动刷新。 + +> **注意**:预处理脚本会在每次构建时重新生成 `SUMMARY.md`,如遇构建报错请先检查 `index.md` 中 `toc` 块的格式是否正确。 + +--- + +## 写作规范 + +详细的自定义语法(公式、图片标签、文献引用、代码块等)及图片规范,请参阅 **[写作样式规范](style_zh.md)**。 + +--- + +## 提交流程 + +1. **Fork** 本仓库并创建功能分支: + ```bash + git checkout -b feat/chapter-xxx-section-yyy + ``` + +2. **本地构建验证**:修改完成后运行 `bash build_mdbook_v2.sh`,确保无报错 + +3. **提交代码**:遵循语义化提交信息 + ```bash + git commit -m "feat(zh): 新增第X章第Y节内容" + git commit -m "feat(en): Add content for chapter X section Y" + git commit -m "ci: update main.yml" + ``` + 常用前缀:`feat`(新内容)、`fix`(修正错误)、`refactor`(重组结构)、`style`(格式调整)、`ci`(构建流程更新) + +4. **发起 Pull Request**:目标分支为 `main`,请使用 PR 模板: + + - [中文 PR 模板](.github/PULL_REQUEST_TEMPLATE/zh.md) + - [英文 PR 模板](.github/PULL_REQUEST_TEMPLATE/en.md) + +5. **代码审查**:PR要求至少有一位非本人Contributor进行检查,且github action将会自动验证新增内容是否可以编译通过 + +--- + +## 常见问题 + +**Q:如何添加新章节?** + +- 在 `v2/zh_chapters/` 下新建 `chapter_<名称>/` 目录 +- 创建 `index.md`,在其中使用 `toc` 块列出各节 +- 在全书 `v2/zh_chapters/index.md` 的 `toc` 块中注册新章节 +- 确保本地构建通过后再提交 PR + +**Q:参考文献如何添加?** + +在 `mlsys.bib` 中添加 BibTeX 格式的文献条目,然后在正文中使用 `:cite:`key`` 引用。 + +**Q:构建时提示找不到图片怎么处理?** + +检查图片路径是否以 `../img/` 开头(相对于章节目录),以及图片文件是否已提交至 `img/` 目录。 diff --git a/CONTRIBUTING/info.md b/CONTRIBUTING/info.md deleted file mode 100644 index 055eebb..0000000 --- a/CONTRIBUTING/info.md +++ /dev/null @@ -1,53 +0,0 @@ -# Build & Environment Guide / 环境安装与编译指南 - -## Environment Setup / 环境安装 - -The book is deployed on GitHub using mdbook. We recommend installing mdbook via Rust's native package manager cargo. - -机器学习系统书籍部署在GitHub是依赖于mdbook工具实现的。我们推荐使用rust的原生包管理器cargo安装mdbook。 - -```bash -# Install Rust toolchain to get cargo / 安装rust工具链,获取cargo -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -cargo install mdbook -``` - -## Building HTML / 编译HTML版本 - -Clone the [openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) repository first. All build commands should be run from the repository root. - -在编译前先下载[openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) , 所有的编译命令都在这个文件目录内执行。 - -```bash -git clone https://github.com/openmlsys/openmlsys-zh.git -cd openmlsys-zh -``` - -Build HTML using mdbook. Please use the build scripts to ensure the homepage is correctly merged into the book. - -使用mdbook工具编译HTML。 请尽量使用build脚本进行编译,保证首页正确合并到书籍中去。 - -```bash -sh build_mdbook_v1.sh -sh build_mdbook_v2.sh -``` - -Build outputs are placed in `.mdbook-v2/book` (English) and `.mdbook-v2-zh/book` (Chinese). The `tools/assemble_docs_publish_tree.py` script assembles the final bilingual publication tree, which is then copied to openmlsys.github.io for deployment. - -生成的html会在`.mdbook-v2/book`或者`.mdbook-v2-zh/book`下。此时我们可以使用`tools/assemble_docs_publish_tree.py`组装最终的双语发布版本,然后将其拷贝至openmlsys.github.io的docs发布。 - -For the detailed deployment workflow, see `.github/workflows/update_docs.yml`. - -具体工作流可以参考`.github/workflows/update_docs.yml` - -## Style Guide / 样式规范 - -Please follow the project [style guide](style.md) when contributing. - -贡献请遵照本教程的[样式规范](style.md)。 - -## Terminology / 中英文术语对照 - -Please refer to the [terminology guide](terminology.md) for translations. - -翻译请参照[中英文术语对照](terminology.md)。 diff --git a/CONTRIBUTING/info_en.md b/CONTRIBUTING/info_en.md new file mode 100644 index 0000000..2d1d266 --- /dev/null +++ b/CONTRIBUTING/info_en.md @@ -0,0 +1,39 @@ +# Build & Environment Guide + +## Environment Setup + +The book is deployed on GitHub using mdbook. We recommend installing mdbook via Rust's native package manager cargo. + +```bash +# Install Rust toolchain to get cargo +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +cargo install mdbook +``` + +## Building HTML + +Clone the [openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) repository first. All build commands should be run from the repository root. + +```bash +git clone https://github.com/openmlsys/openmlsys-zh.git +cd openmlsys-zh +``` + +Build HTML using mdbook. Please use the build scripts to ensure the homepage is correctly merged into the book. + +```bash +sh build_mdbook_v1.sh +sh build_mdbook_v2.sh +``` + +Build outputs are placed in `.mdbook-v2/book` (English) and `.mdbook-v2-zh/book` (Chinese). The `tools/assemble_docs_publish_tree.py` script assembles the final bilingual publication tree, which is then copied to openmlsys.github.io for deployment. + +For the detailed deployment workflow, see `.github/workflows/update_docs.yml`. + +## Style Guide + +Please follow the project [style guide](style_en.md) when contributing. + +## Terminology + +Please refer to the [terminology guide](terminology.md) for translations. diff --git a/CONTRIBUTING/info_zh.md b/CONTRIBUTING/info_zh.md new file mode 100644 index 0000000..44e98d1 --- /dev/null +++ b/CONTRIBUTING/info_zh.md @@ -0,0 +1,39 @@ +# 环境安装与编译指南 + +## 环境安装 + +机器学习系统书籍部署在GitHub是依赖于mdbook工具实现的。我们推荐使用rust的原生包管理器cargo安装mdbook。 + +```bash +# 安装rust工具链,获取cargo +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +cargo install mdbook +``` + +## 编译HTML版本 + +在编译前先下载[openmlsys-zh](https://github.com/openmlsys/openmlsys-zh) , 所有的编译命令都在这个文件目录内执行。 + +```bash +git clone https://github.com/openmlsys/openmlsys-zh.git +cd openmlsys-zh +``` + +使用mdbook工具编译HTML。 请尽量使用build脚本进行编译,保证首页正确合并到书籍中去。 + +```bash +sh build_mdbook_v1.sh +sh build_mdbook_v2.sh +``` + +生成的html会在`.mdbook-v2/book`或者`.mdbook-v2-zh/book`下。此时我们可以使用`tools/assemble_docs_publish_tree.py`组装最终的双语发布版本,然后将其拷贝至openmlsys.github.io的docs发布。 + +具体工作流可以参考`.github/workflows/update_docs.yml` + +## 样式规范 + +贡献请遵照本教程的[样式规范](style_zh.md)。 + +## 中英文术语对照 + +翻译请参照[中英文术语对照](terminology.md)。 diff --git a/CONTRIBUTING/issue.md b/CONTRIBUTING/issue.md deleted file mode 100644 index 26bd62c..0000000 --- a/CONTRIBUTING/issue.md +++ /dev/null @@ -1,19 +0,0 @@ -# Issue Labels / Issue 的 label - -Our issues use the following labels: - -目前我们的issue主要有如下label: - -- **great suggestion**: The issue is a good writing suggestion from a user / 表示该issue是用户为本书的内容提供的写作建议,并且该建议是一个很好的建议 -- **discussion**: The issue is a discussion about the content, or a suggestion still under deliberation / 表示该issue是用户针对文章内容进行特定讨论,或用户对内容进行了建议并且该建议还处在商讨中 -- **to be confirmed**: The issue has been assigned to a chapter author who has not yet responded / 表示该issue被assign给了章节作者,但是目前章节作者并没有回复处理这个issue -- **confirmed**: The chapter author has confirmed the issue / 表示该issue被章节作者已经确认 -- **fixed**: The related PR has been approved/merged / 表示该issue相关的pr被approve/merge - -## Typical Issue Lifecycle / 常规状态变换 - -A typical content-correction issue follows this lifecycle: - -常规而言,一个针对书籍内容校正的issue的状态变换应该为: - - to be confirmed ----> confirmed ----> fixed diff --git a/CONTRIBUTING/issue_en.md b/CONTRIBUTING/issue_en.md new file mode 100644 index 0000000..362345e --- /dev/null +++ b/CONTRIBUTING/issue_en.md @@ -0,0 +1,15 @@ +# Issue Labels + +Our issues use the following labels: + +- **great suggestion**: The issue is a good writing suggestion from a user +- **discussion**: The issue is a discussion about the content, or a suggestion still under deliberation +- **to be confirmed**: The issue has been assigned to a chapter author who has not yet responded +- **confirmed**: The chapter author has confirmed the issue +- **fixed**: The related PR has been approved/merged + +## Typical Issue Lifecycle + +A typical content-correction issue follows this lifecycle: + + to be confirmed ----> confirmed ----> fixed diff --git a/CONTRIBUTING/issue_zh.md b/CONTRIBUTING/issue_zh.md new file mode 100644 index 0000000..fbfd467 --- /dev/null +++ b/CONTRIBUTING/issue_zh.md @@ -0,0 +1,15 @@ +# Issue 的 label + +目前我们的issue主要有如下label: + +- **great suggestion**: 表示该issue是用户为本书的内容提供的写作建议,并且该建议是一个很好的建议 +- **discussion**: 表示该issue是用户针对文章内容进行特定讨论,或用户对内容进行了建议并且该建议还处在商讨中 +- **to be confirmed**: 表示该issue被assign给了章节作者,但是目前章节作者并没有回复处理这个issue +- **confirmed**: 表示该issue被章节作者已经确认 +- **fixed**: 表示该issue相关的pr被approve/merge + +## 常规状态变换 + +常规而言,一个针对书籍内容校正的issue的状态变换应该为: + + to be confirmed ----> confirmed ----> fixed diff --git a/CONTRIBUTING/reference_guide.md b/CONTRIBUTING/reference_guide.md deleted file mode 100644 index b8441a6..0000000 --- a/CONTRIBUTING/reference_guide.md +++ /dev/null @@ -1,38 +0,0 @@ -# Reference Citation Guide / 参考文献引用方式 - -All references are maintained in `mlsys.bib`. - -所有参考文献统一维护在 `mlsys.bib` 中。 - -## Adding Bibliography Entries / 添加文献条目 - -Add a BibTeX entry to `mlsys.bib`. Before adding, search for existing keys to avoid duplicates: - -在 `mlsys.bib` 中添加 BibTeX 格式的条目,添加前请先检索是否已存在同名 key: - -```bibtex -@inproceedings{cnn2015, - title = {CNN}, - author = {xxx}, - year = {2015}, - keywords = {xxx} -} -``` - -## In-text Citations / 正文引用 - -A space is required before the citation directive: - -引用时前面需要有一个空格: - -1. Single reference / 单篇参考文献 - ``` - This article references the paper :cite:`cnn2015` - 这篇文章参考了论文 :cite:`cnn2015` - ``` - -2. Multiple references separated by commas / 多篇参考文献用逗号分隔 - ``` - This article references the papers :cite:`cnn2015,rnn2015` - 这篇文章参考了论文 :cite:`cnn2015,rnn2015` - ``` diff --git a/CONTRIBUTING/reference_guide_en.md b/CONTRIBUTING/reference_guide_en.md new file mode 100644 index 0000000..b28abc9 --- /dev/null +++ b/CONTRIBUTING/reference_guide_en.md @@ -0,0 +1,30 @@ +# Reference Citation Guide + +All references are maintained in `mlsys.bib`. + +## Adding Bibliography Entries + +Add a BibTeX entry to `mlsys.bib`. Before adding, search for existing keys to avoid duplicates: + +```bibtex +@inproceedings{cnn2015, + title = {CNN}, + author = {xxx}, + year = {2015}, + keywords = {xxx} +} +``` + +## In-text Citations + +A space is required before the citation directive: + +1. Single reference + ``` + This article references the paper :cite:`cnn2015` + ``` + +2. Multiple references separated by commas + ``` + This article references the papers :cite:`cnn2015,rnn2015` + ``` diff --git a/CONTRIBUTING/reference_guide_zh.md b/CONTRIBUTING/reference_guide_zh.md new file mode 100644 index 0000000..4977c23 --- /dev/null +++ b/CONTRIBUTING/reference_guide_zh.md @@ -0,0 +1,30 @@ +# 参考文献引用方式 + +所有参考文献统一维护在 `mlsys.bib` 中。 + +## 添加文献条目 + +在 `mlsys.bib` 中添加 BibTeX 格式的条目,添加前请先检索是否已存在同名 key: + +```bibtex +@inproceedings{cnn2015, + title = {CNN}, + author = {xxx}, + year = {2015}, + keywords = {xxx} +} +``` + +## 正文引用 + +引用时前面需要有一个空格: + +1. 单篇参考文献 + ``` + 这篇文章参考了论文 :cite:`cnn2015` + ``` + +2. 多篇参考文献用逗号分隔 + ``` + 这篇文章参考了论文 :cite:`cnn2015,rnn2015` + ``` diff --git a/CONTRIBUTING/style.md b/CONTRIBUTING/style_en.md similarity index 51% rename from CONTRIBUTING/style.md rename to CONTRIBUTING/style_en.md index 884dab8..3af3d2c 100644 --- a/CONTRIBUTING/style.md +++ b/CONTRIBUTING/style_en.md @@ -178,188 +178,3 @@ Example citations in body text: This chapter references the paper :cite:`cnn2015`. Multiple citations: :cite:`cnn2015,rnn2015`. ``` - ---- - ---- - -# 写作样式规范 - -本文档规定了 v2 章节内容的写作格式与样式要求。所有贡献者在撰写或修改内容时请遵循以下规范。 - -> **注意:** LaTeX 转 Markdown 的工作流已**废弃**。v2 中所有内容直接使用 Markdown 书写,无需通过 Pandoc 等工具转换。 - ---- - -## 目录 - -- [文件结构](#文件结构) -- [自定义语法](#自定义语法) -- [图片规范](#图片规范) -- [表格规范](#表格规范) -- [代码块规范](#代码块规范) -- [参考文献](#参考文献) - ---- - -## 文件结构 - -- 每章对应 `v2/zh_chapters/_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/CONTRIBUTING/style_zh.md b/CONTRIBUTING/style_zh.md new file mode 100644 index 0000000..0d9d010 --- /dev/null +++ b/CONTRIBUTING/style_zh.md @@ -0,0 +1,180 @@ +# 写作样式规范 + +本文档规定了 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/README.md b/README.md index 81844e3..67e8efa 100644 --- a/README.md +++ b/README.md @@ -99,14 +99,14 @@ sh build_mdbook_v2.sh # 中文版生成结果位于 .mdbook-v2-zh/book ``` -更多细节请参考 [构建指南](CONTRIBUTING/info.md)。 +更多细节请参考 [构建指南](CONTRIBUTING/info_zh.md)。 ## 贡献指南 -我们欢迎任何形式的贡献,详细流程请参阅 **[贡献指南](CONTRIBUTING/CONTRIBUTING.md)**。 +我们欢迎任何形式的贡献,详细流程请参阅 **[贡献指南](CONTRIBUTING/CONTRIBUTING_zh.md)**。 提交前请阅读: -- [写作样式规范](CONTRIBUTING/style.md) +- [写作样式规范](CONTRIBUTING/style_zh.md) - [中英文术语对照](CONTRIBUTING/terminology.md) ## 社区 diff --git a/README_EN.md b/README_EN.md index c96a0b1..c4e16ce 100644 --- a/README_EN.md +++ b/README_EN.md @@ -101,14 +101,14 @@ sh build_mdbook_v2.sh # Chinese output: .mdbook-v2-zh/book ``` -For more details, see the [Build Guide](CONTRIBUTING/info.md). +For more details, see the [Build Guide](CONTRIBUTING/info_en.md). ## Contributing -We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](CONTRIBUTING/CONTRIBUTING.md)**. +We welcome all forms of contributions. For the full workflow, see the **[Contributing Guide](CONTRIBUTING/CONTRIBUTING_en.md)**. Before contributing, please read: -- [Writing Style Guide](CONTRIBUTING/style.md) +- [Writing Style Guide](CONTRIBUTING/style_en.md) - [Terminology Guide](CONTRIBUTING/terminology.md) ## Community