diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..2932af8
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    pre_install:
+      # 安装 Rust 工具链以编译 PyO3 扩展
+      - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+      - source $HOME/.cargo/env
+      - pip install maturin
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    # 从源码安装 chanlun-py（maturin develop）
+    - method: pip
+      path: chanlun-py
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..b6960f1
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,55 @@
+# API 参考
+
+## 枚举
+
+| 类 | 说明 |
+|---|------|
+| `买卖点类型` | 一卖点、一买点、二卖点、二买点、三卖点、三买点 |
+| `相对方向` | 向上、向下、向上缺口、向下缺口、衔接向上、衔接向下 |
+| `分型结构` | 顶分型、底分型、散（无分型） |
+
+## 数据
+
+| 类 | 说明 |
+|---|------|
+| `K线` | 原始 OHLCV 数据，内嵌 MACD/RSI/KDJ 指标 |
+| `缠论K线` | 经包含处理后的 K 线，有方向（向上/向下）、分型结构标记 |
+| `缺口` | 前后两段区间的相对位置关系 |
+
+## 结构
+
+| 类 | 说明 |
+|---|------|
+| `分型` | 顶/底分型，由左中右三根缠K构成 |
+| `虚线` | 笔/线段的通用数据结构 |
+| `线段特征` | 线段特征序列，用于分析线段力度 |
+| `特征分型` | 特征分型结构 |
+
+## 指标
+
+| 类 | 说明 |
+|---|------|
+| `平滑异同移动平均线` | MACD — EMA 快慢线 + 信号线 + 柱状图 |
+| `相对强弱指数` | RSI — Wilder SMA 平滑，含超买超卖阈值 |
+| `随机指标` | KDJ — RSV → K → D → J，含超买超卖阈值 |
+| `指标` | 指标工具类 — `K线取值` 等静态方法 |
+
+## 算法
+
+| 类 | 说明 |
+|---|------|
+| `笔` | 笔划分算法（创建、分析、弱化、分析前检查） |
+| `线段` | 线段划分算法（分析、武斗、武终、分割序列） |
+| `中枢` | 中枢识别算法（延伸、扩展、第三买卖线） |
+| `背驰分析` | MACD/斜率/测度背离检测 |
+
+## 业务
+
+| 类 | 说明 |
+|---|------|
+| `缠论配置` | 50+ 参数集中控制所有分析阶段的行为 |
+| `观察者` | 单周期分析器，持有所有层级序列 |
+| `基础买卖点` | 买卖点数据结构 |
+| `买卖点` | 继承基础买卖点，添加工厂类方法 |
+| `K线合成器` | 将小周期 K 线合成为大周期 K 线 |
+| `立体分析器` | 多周期分析器，含 K线合成器 + 每周期观察者 |
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..266a9d2
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,46 @@
+# Sphinx 配置 — chanlun 缠论技术分析库
+#
+# 使用 MyST 解析器支持 Markdown，Furo 主题
+
+import os
+import sys
+
+# 确保文档构建时能 import chanlun
+sys.path.insert(0, os.path.abspath(".."))
+
+# ---- 项目信息 ----
+project = "chanlun"
+copyright = "2026, YuWuKunCheng"
+author = "YuWuKunCheng"
+release = "26.5.103"
+language = "zh_CN"
+
+# ---- 扩展 ----
+extensions = [
+    "myst_parser",  # Markdown 支持
+    "sphinx.ext.viewcode",  # 添加源码链接
+    "sphinx.ext.intersphinx",  # 跨项目文档链接
+]
+
+# ---- MyST 配置 ----
+myst_enable_extensions = [
+    "colon_fence",  # ::: 围栏代码块
+    "fieldlist",  # 字段列表
+]
+myst_heading_anchors = 3
+
+# ---- 主题 ----
+html_theme = "furo"
+html_title = "chanlun — 缠论技术分析库"
+html_theme_options = {
+    "source_repository": "https://github.com/yuwukuncheng/chanlun.rs",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+
+# ---- 跨项目链接 ----
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+add_module_names = False
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..0f1e0b9
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,45 @@
+# chanlun — 缠论技术分析库
+
+基于 Rust + PyO3 的高性能缠论技术分析 Python 绑定，API 参考 `chan.py` 设计，高度兼容。
+
+## 特性
+
+- **高性能**：核心算法用 Rust 实现，通过 PyO3 暴露为 Python 原生模块
+- **完全兼容**：类名、方法名、字段名与 `chan.py` 保持一致
+- **流式计算**：逐 K 线增量更新，无需重复计算
+- **多周期分析**：内置 K 线合成器和立体分析器，支持跨周期联动
+
+## 安装
+
+```bash
+pip install chanlun
+```
+
+## 快速开始
+
+```python
+import chanlun
+
+config = chanlun.缠论配置()
+obs = chanlun.观察者.读取数据文件("BTCUSD-300.nb", config)
+
+print(f"K线: {len(obs.普通K线序列)}")
+print(f"笔:   {len(obs.笔序列)}")
+print(f"线段: {len(obs.线段序列)}")
+print(f"中枢: {len(obs.中枢序列)}")
+```
+
+```{toctree}
+:hidden:
+:caption: 文档导航
+
+api
+```
+
+```{toctree}
+:hidden:
+:caption: 外部链接
+
+GitHub <https://github.com/yuwukuncheng/chanlun.rs>
+PyPI <https://pypi.org/project/chanlun/>
+```
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..6ef77ba
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx>=8.0
+myst-parser>=4.0
+furo>=2024.0