build system for docs (#1404)

Author: jzhang533

.gitignore

@@ -7,3 +7,5 @@ __pycache__/
 output
 demo_data/index-cache
 log
+docs/site/
+uv.lock

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: docs/mkdocs.yml
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

README.md

@@ -6,7 +6,7 @@
 
 [ERNIE Bot](https://ernie.baidu.com/) |  [🤗Hugging Face](https://huggingface.co/baidu) | [AI Studio](https://aistudio.baidu.com/modelsoverview)
 
-📑 [Blog](https://yiyan.baidu.com/blog/posts/ernie4.5) | 📚 [Cookbook](./cookbook/) | 📑 [Paper](https://yiyan.baidu.com/blog/publication/)  | 🛠️ [Training](./docs/erniekit.md)  | ⚡️ [Deploy](https://github.com/PaddlePaddle/FastDeploy)
+📑 [Blog](https://yiyan.baidu.com/blog/posts/ernie4.5) | 📚 [Cookbook](./cookbook/) | 📑 [Paper](https://yiyan.baidu.com/blog/publication/)  | 🛠️ [Training](./docs/source/erniekit.md)  | ⚡️ [Deploy](https://github.com/PaddlePaddle/FastDeploy)
 
 <a href="https://trendshift.io/repositories/14169" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14169" alt="PaddlePaddle%2FERNIE | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
@@ -22,7 +22,7 @@
 **[2025-10] 🔥 Released ERNIEKit v1.4:**
 
 - **New Features**
-    - VL Model Training: Support SFT for [PaddleOCR-VL-0.9B]((https://huggingface.co/PaddlePaddle/PaddleOCR-VL/tree/main/PaddleOCR-VL-0.9B)) model. More details in [PaddleOCR-VL-0.9B SFT](./docs/paddleocr_vl_sft.md).
+    - VL Model Training: Support SFT for [PaddleOCR-VL-0.9B]((https://huggingface.co/PaddlePaddle/PaddleOCR-VL/tree/main/PaddleOCR-VL-0.9B)) model. More details in [PaddleOCR-VL-0.9B SFT](./docs/source/paddleocr_vl_sft.md).
     - Dataflow : Support padding-free startegy.
         - Packing data within a batch into a sequence to avoid padding, thereby reducing GPU memory usage and accelerating training.
 
@@ -178,7 +178,7 @@ In the non-thinking mode, ERNIE-4.5-VL exhibits outstanding proficiency in visua
 
 ## Model Development
 
-ERNIE 4.5 models are trained and deployed for inference using the [PaddlePaddle]((https://github.com/PaddlePaddle/Paddle)) framework. The full workflow of training, compression, and inference for ERNIE 4.5 is supported through the [ERNIEKit](./docs/erniekit.md) and [FastDeploy](https://github.com/PaddlePaddle/FastDeploy) toolkit. The table below details the feature matrix of the ERNIE 4.5 model family for training and inference.
+ERNIE 4.5 models are trained and deployed for inference using the [PaddlePaddle]((https://github.com/PaddlePaddle/Paddle)) framework. The full workflow of training, compression, and inference for ERNIE 4.5 is supported through the [ERNIEKit](./docs/source/erniekit.md) and [FastDeploy](https://github.com/PaddlePaddle/FastDeploy) toolkit. The table below details the feature matrix of the ERNIE 4.5 model family for training and inference.
 <div align="center">
 
 | Model             |  Training      |  Inference              |
@@ -209,7 +209,7 @@ _Note: For different ERNIE 4.5 model, we provide diverse quantization schemes us
 * Quantization-Aware Training (QAT)
 * Post-Training Quantization (PTQ) [WIP]
 
-Minimum hardware requirements for training each model are documented [here](./docs/erniekit.md).
+Minimum hardware requirements for training each model are documented [here](./docs/source/erniekit.md).
 
 
 #### Quick Start
@@ -223,7 +223,7 @@ huggingface-cli download baidu/ERNIE-4.5-0.3B-Paddle --local-dir baidu/ERNIE-4.5
 erniekit train examples/configs/ERNIE-4.5-0.3B/sft/run_sft_8k.yaml
 ```
 
-For detailed guides on installation, CLI usage, WebUI, multi-node training, and advanced features, please refer to [ERNIEKit Training Document](./docs/erniekit.md).
+For detailed guides on installation, CLI usage, WebUI, multi-node training, and advanced features, please refer to [ERNIEKit Training Document](./docs/source/erniekit.md).
 
 For detailed guides on High-performance pre-training, please refer to [Pre-Training Document](./examples/pre-training/README.md).
 

docs/README.md

@@ -0,0 +1,34 @@
+# ERNIE Documentation
+
+Source files for contents presented at [https://ernie.readthedocs.io/](https://ernie.readthedocs.io/en/latest/).
+
+## Contributing
+
+You can build the docs as web pages locally.
+
+```bash
+cd docs
+uv venv
+source .venv/bin/activate
+uv run mkdocs serve
+```
+
+### Markdown Linting
+
+We use `pymarkdown` to lint markdown files. Install the linting tools with:
+
+```bash
+uv sync --extra lint
+```
+
+Check all markdown files:
+
+```bash
+uv run pymarkdown scan source/
+```
+
+Auto-fix issues (where supported):
+
+```bash
+uv run pymarkdown fix source/
+```

docs/mkdocs.yml

@@ -0,0 +1,106 @@
+site_name: ERNIE Docs
+site_url: !ENV READTHEDOCS_CANONICAL_URL
+repo_url: https://github.com/PaddlePaddle/ERNIE
+repo_name: PaddlePaddle/ERNIE
+edit_uri: edit/develop/docs/source/
+docs_dir: source
+site_dir: site
+strict: false
+
+theme:
+  name: material
+  logo: assets/images/favicon.ico
+  favicon: assets/images/favicon.ico
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      primary: white
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      toggle:
+        icon: material/brightness-2
+        name: Switch to system preference
+  features:
+    - content.action.edit
+    - content.code.copy
+    - content.tabs.link
+    - navigation.tracking
+    - navigation.sections
+    - navigation.top
+    - search.highlight
+    - search.share
+    - toc.follow
+
+plugins:
+  - search
+  - meta
+  - awesome-nav
+  - glightbox
+  - i18n:
+      docs_structure: suffix
+      fallback_to_default: true
+      languages:
+        - locale: en
+          default: true
+          name: English
+          build: true
+        - locale: zh
+          name: 中文
+          build: true
+          nav_translations:
+            Home: 首页
+
+extra:
+  alternate:
+    - name: English
+      link: /
+      lang: en
+    - name: Chinese
+      link: /zh/
+      lang: zh
+
+markdown_extensions:
+  - attr_list
+  - md_in_html
+  - admonition
+  - pymdownx.details
+  # For content tabs
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+      alternate_style: true
+  # For code highlighting
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  # For emoji and icons
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  # For in page [TOC] (not sidebar)
+  - toc:
+      permalink: true
+  # For math rendering
+  - mdx_math:
+      enable_dollar_delimiter: true
+
+extra_javascript:
+  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
+
+use_directory_urls: false

docs/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "ernie-docs"
+version = "0.1.0"
+description = "Documentation for ERNIE"
+requires-python = ">=3.10"
+dependencies = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-api-autonav",
+    "mkdocs-awesome-nav",
+    "mkdocs-glightbox",
+    "python-markdown-math",
+    "mkdocs-same-dir",
+    "mkdocs-static-i18n",
+]
+
+[project.optional-dependencies]
+lint = [
+    "pymarkdownlnt",
+]
+
+[tool.pymarkdown.plugins]
+# Disable line length check (too strict for documentation)
+md013.enabled = false
+# Allow multiple top-level headings (common in docs)
+md025.enabled = false
+# Allow duplicate headings (common in multi-section docs)
+md024.enabled = false
+# Allow emphasis as headers (stylistic choice)
+md036.enabled = false
+# Set list indent to 4 spaces (Python style)
+md007.indent = 4
+# Allow both dash and asterisk for unordered lists
+md004.enabled = false
+# Allow code blocks without blank lines around them
+md031.enabled = false
+# Allow lists without blank lines around them
+md032.enabled = false
+# Allow headings without blank lines around them
+md022.enabled = false
+# Allow bare URLs
+md034.enabled = false

docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs>=1.5.0
+mkdocs-material>=9.5.0
+mkdocs-api-autonav
+mkdocs-awesome-nav
+mkdocs-glightbox
+python-markdown-math
+mkdocs-same-dir
+mkdocs-static-i18n>=1.2.0

docs/source/README.md

@@ -0,0 +1,15 @@
+# ERNIE Documentation
+
+Welcome to the ERNIE documentation.
+
+## Guides
+
+- [ERNIEKit Overview & Installation](erniekit.md)
+- [WebUI & CLI Usage](cli_webui_usage.md)
+- [PaddleOCR-VL SFT](paddleocr_vl_sft.md)
+- [Datasets Guide](datasets.md)
+- [Training & Evaluation Arguments](training_eval_args.md)
+- [Chat Arguments](chat_args.md)
+- [Export Arguments](export_args.md)
+- [FP8 Quantization-Aware Training (QAT)](fp8_qat.md)
+- [WINT8 Mixed Precision LoRA](wint8mix_lora.md)