anyin233 6c9673a659 build: migrate docs build and deploy to mdbook (#490)
* build: add mdbook support for zh chapters

Add mdBook configuration rooted at zh_chapters, generate and commit SUMMARY.md, rewrite d2l-specific directives through a Python preprocessor, refresh chapter resource symlinks from the build scripts, and ignore local build-only links and helper directories.

* feat: add raw HTML inline and frontpage layout support for mdbook preprocessor

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add dark mode image background for mdbook dark themes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add resource symlinks and repo root static fallback to mdbook build

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add BibTeX citation support with inline links and bibliography

Parse mlsys.bib to generate author-year inline citations linked to
per-page bibliography sections. Missing bib keys degrade gracefully
to plain text placeholders.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: switch citation display to footnote style

Use numbered superscript references [1] [2] inline with an ordered
list bibliography at page bottom. Each entry has a back-link (↩)
to the citation site.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: strip LaTeX escapes outside math mode in mdbook preprocessor

Remove \_, \%, \#, \& escapes from text outside $...$ math spans
while preserving them inside math mode for MathJax compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* style: set frontpage author grid to 6 columns and widen main content area

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: group mdbook toc by part titles

* fix: enable inline math rendering in mdbook

* build: migrate docs publishing to mdbook

Move the English root site to mdBook, keep the Chinese site as a sub-book, and update CI/deploy to publish .mdbook outputs to docs/ and docs/cn/. Also add regression coverage for placeholder skipping, publish-tree assembly, and shared resource setup.

* ci: use official pages deployment workflow

Switch the docs deployment workflow to the official GitHub Pages actions flow and verify it uses Pages action outputs for the deployment URL.

* feat: add homepage language switch links

Inject a homepage-only language switch into the mdBook frontpage wrapper so the English homepage links to the Chinese homepage and the Chinese homepage links back to the English homepage.

* fix: correct english homepage frontpage

Add an English-specific frontpage template so the default homepage no longer falls back to the Chinese frontpage, and clear homepage image backgrounds in the frontpage wrapper CSS.

* fix: align english homepage author grid

Top-align the English homepage author cards, enlarge the row gap, and normalize avatar sizing so author portraits line up consistently.

* fix: restore dark mode body image backgrounds

Apply light gray backgrounds to body images in dark themes for both English and Chinese mdBook themes while explicitly excluding homepage frontpage images.

* fix: restyle homepage language switch button

Move the homepage language switch below the GitHub star button and restyle it to match the same button family on both the English and Chinese homepages.

* fix: center homepage content container

Align the English and Chinese homepage frontpage wrapper with the main content container so homepage content is centered like normal body content.

* fix: stack english homepage footer copy

Keep the English homepage contributor and errata footer lines in normal block flow so each sentence stays on its own line instead of being laid out as author-grid columns.

* fix: widen centered homepage container

Keep the homepage frontpage wrapper centered while ensuring it uses at least 80% of the available content area, without changing normal body page layout.

* fix: widen homepage main content area

Apply a homepage-only override so mdbook-content > main uses at least 80% of the available content width while keeping normal body pages on the default layout.

* ci: use peaceiris action for mdbook

Replace manual mdBook installation in CI and Pages workflows with peaceiris/actions-mdbook@v2 and keep a regression test to ensure the action stays in use.

* fix: reduce homepage main width floor

Lower the homepage-only mdbook-content > main minimum width from 80% to 65% while leaving normal body pages unchanged.

* build: switch math rendering to mdbook-katex

Use mdbook-katex in pre-render mode for both books, pin mdBook to a compatible version, update build scripts and workflows, and replace the old MathJax regression tests with KaTeX coverage.

* Revert "build: switch math rendering to mdbook-katex"

This reverts commit b9cf38a5d1.

* build: switch math rendering from MathJax to mdbook-typst-math

* ci: deploy docs to openmlsys.github.io repo

* fix: convert pandoc tables to GFM pipe tables for mdbook

* feat: convert :eqlabel:/:eqref: to MathJax \tag/\label/\eqref

- Add process_equation_labels() to inject \tag{n}\label{name} into
  preceding $$ equations, replacing :eqlabel: directives
- Change :eqref: conversion from backtick code to $\eqref{name}$
  for clickable cross-references
- Add TeX.equationNumbers.autoNumber:"none" to MathJax config to
  prevent conflicts with manual \tag numbering
- Add tests for single-line, multi-line, and sequential numbering

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: cache mdbook-typst-math binary in workflows

* feat: add LaTeX-to-Typst math converter with eqref/tag support

* feat: integrate LaTeX-to-Typst conversion into zh preprocessor

* fix: strip LaTeX escapes only outside math spans and code blocks

* fix: load references/*.bib so all citations render correctly

* fix: skip citations with no bib entry instead of rendering raw keys

* ci: remove redundant CI workflow, keep only deploy workflow

* ci: Add CI workflow for testing and building mdBook

* ci: remove concurrency settings from update_docs.yml

Removed concurrency settings from the update_docs workflow.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 16:17:37 +00:00
2024-02-18 17:49:56 +08:00
2023-02-16 17:25:09 +08:00
2023-03-29 00:28:49 +08:00
2022-03-01 15:22:19 +00:00
2023-03-29 00:28:49 +08:00

OpenMLSys Logo

CI Book Online License GitHub Stars

中文 | English


Machine Learning Systems: Design and Implementation

An open-source book explaining the design principles and implementation experience of modern machine learning systems, covering the complete technology stack from programming interfaces and computational graphs to compilers and distributed training.

Read Online: openmlsys.github.io

Table of Contents

Target Audience

  • Students: Those who have mastered machine learning fundamentals and want to deeply understand the design and implementation of modern ML systems.
  • Researchers: Those who need to develop custom operators or leverage distributed execution for large model development.
  • Engineers: Those responsible for building ML infrastructure and need to tune system performance or customize ML systems for business needs.

Content Overview

The book is organized into three parts: Fundamentals, Advanced Topics, and Extensions.

Part I: Fundamentals

Chapter Content
Programming Interface Framework API design, ML workflows, deep learning model definition, C/C++ framework development
Computational Graph Graph components, generation methods, scheduling strategies, automatic differentiation

Part II: Advanced Topics

Chapter Content
Compiler Frontend & IR Type inference, intermediate representation (IR), automatic differentiation, common optimization passes
Compiler Backend & Runtime Graph optimization, operator selection, memory allocation, compute scheduling and execution
Hardware Accelerators GPU/Ascend architecture, high-performance programming interfaces (CUDA/CANN)
Data Processing Usability, efficiency, order preservation, distributed data processing
Model Deployment Model conversion, compression, inference, and security
Distributed Training Data parallelism, model parallelism, pipeline parallelism, collective communication, parameter servers

Part III: Extensions

Chapter Content
Recommender Systems Recommendation principles, large-scale industrial architecture
Federated Learning Federated learning methods, privacy protection, system implementation
Reinforcement Learning Systems Single-agent and multi-agent RL systems
Explainable AI Systems XAI methods and production practices
Robot Learning Systems Robot perception, planning, control, and system safety

Build Guide

Prerequisites

  • Python >= 3.10
  • pandoc >= 2.19

Installation

# Clone the repository
git clone https://github.com/openmlsys/openmlsys-zh.git
cd openmlsys-zh

# Install d2lbook
git clone https://github.com/openmlsys/d2l-book.git
cd d2l-book && pip install . && cd ..

# Install Python dependencies
pip install -r requirements.txt

Build HTML

sh build_html.sh
# Output is in _build/html/

For more details, see the Build Guide.

Contributing

We welcome all forms of contributions, including:

  • Errata: If you find text or figure errors, please open an Issue and @ the chapter editors, or submit a PR directly.
  • Content updates: Submit PRs to update or add Markdown files.
  • New chapters: We welcome community contributions on topics such as meta-learning systems, automatic parallelism, cluster scheduling, green AI, and graph learning.

Before contributing, please read:

Community

Join our WeChat group by scanning the QR code in info/mlsys_group.png.

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Description
《Machine Learning Systems: Design and Implementation》- Chinese Version
Readme 65 MiB
Languages
TeX 54.8%
Python 29.8%
HTML 8.9%
JavaScript 3%
CSS 2.2%
Other 1.3%