Add bilingual MkDocs documentation site with GitHub Pages deploy

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/genelab/**"
+      - "pyproject.toml"
+      - "README.md"
+      - "CONTRIBUTING.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --extra docs --extra torch-cpu
+      - run: uv run mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -40,4 +40,7 @@ AGENTS.md
 /tmp
 
 # train log
-/logs
+/logs
+
+# mkdocs build output
+/site/

README.md

@@ -91,6 +91,8 @@ uv run genelab project new my_robot_project
 
 ## Documentation
 
+- [Documentation site](https://krahsu.github.io/GeneLab/) — full guides, CLI reference, concepts,
+  and auto-generated API docs. Bilingual (English default, 中文 at `/zh/`).
 - [Examples](examples/README.md): bundled tasks, demo scripts, config overrides, and downstream
   project integration.
 - [中文 README](docs/README_CN.md): concise Chinese project overview.

docs/README_CN.md

@@ -1,5 +1,8 @@
 # GeneLab
 
+> **本文已迁移至 [文档站点（中文）](https://krahsu.github.io/GeneLab/zh/)。**
+> 完整中文文档（CLI 参考、核心概念、API 自动生成参考）请见站点；本文件保留以兼容旧链接。
+
 GeneLab 是一个面向强化学习与机器人研究的 Isaac Lab 风格 API，由
 [Genesis](https://github.com/Genesis-Embodied-AI/Genesis) 提供仿真后端。它保留了机器人、
 环境、任务注册，manager-based MDP 配置，以及 CLI 调度这些常见组织方式。

docs/api/reference.md

@@ -0,0 +1,44 @@
+# API Reference
+
+Auto-generated from the source docstrings via
+[`mkdocstrings`](https://mkdocstrings.github.io/). The API surface below covers GeneLab's public
+core. Extension packages document their own APIs in their own projects.
+
+!!! note "Single-source"
+    The API reference is generated from English docstrings and is shared by both language
+    versions of this site.
+
+---
+
+## `genelab.lab`
+
+The public facade. Most user code should import from here rather than from `genelab.registry`
+directly.
+
+::: genelab.lab
+    options:
+      show_if_no_docstring: true
+
+---
+
+## `genelab.registry`
+
+::: genelab.registry
+    options:
+      show_if_no_docstring: true
+
+---
+
+## `genelab.configs`
+
+::: genelab.configs
+    options:
+      show_if_no_docstring: true
+
+---
+
+## `genelab.cache`
+
+::: genelab.cache
+    options:
+      show_if_no_docstring: true

docs/cli/overview.en.md

@@ -0,0 +1,46 @@
+# CLI overview
+
+`genelab` is exposed as a console script via the `genelab = "genelab.cli:main"` entry point. With
+`uv` you typically invoke it as:
+
+```bash
+uv run genelab [GLOBAL OPTIONS] <subcommand> [ARGS]
+```
+
+## Subcommands
+
+| Subcommand | Purpose |
+|------------|---------|
+| `cache` | Create project-local simulation cache directories (`.cache/`) and set `XDG_CACHE_HOME` / `MPLCONFIGDIR`. |
+| `list robots` | List registered robots from the `ROBOTS` registry. |
+| `list envs` | List registered environments from the `ENVS` registry. |
+| `list tasks` | List registered tasks from the `TASKS` registry. |
+| `play` | Run a registered task in the configured Genesis backend; supports config overrides. |
+| `train` | Train a registered task when an RL runner exists; supports multi-GPU via `torchrun`. |
+| `project new` | Scaffold a new external extension package with all three registries wired up. |
+
+## Global options
+
+These flags work in front of any subcommand:
+
+- `--version` — print the GeneLab version and exit.
+- `--import MODULE` — eagerly import an extension module before dispatching. Repeatable. Useful
+  when you want to load an extension that does not (yet) ship a `genelab.extensions` entry point.
+- `--no-entry-points` — skip auto-discovery of installed extensions via the `genelab.extensions`
+  entry-point group. Combine with `--import` for fully explicit, reproducible loading.
+
+## Extension loading
+
+When the CLI starts, it discovers extensions in this order:
+
+1. **Entry points** under the `genelab.extensions` group (auto, unless `--no-entry-points`).
+2. **Explicit `--import MODULE` flags** (repeatable).
+3. **Programmatic** `genelab.registry.load_extension_module(...)` (used by tests and embedding
+   scripts).
+
+See [Extensions](../concepts/extensions.md) for details on writing a downstream extension.
+
+## See also
+
+- [Play and Train](play-train.md) — config override grammar, multi-GPU training, checkpoints.
+- [Project new](project-new.md) — extension package scaffolding.

docs/cli/overview.zh.md

@@ -0,0 +1,44 @@
+# CLI 总览
+
+`genelab` 通过 `genelab = "genelab.cli:main"` entry point 暴露为命令行脚本。配合 `uv` 时通常这样调用：
+
+```bash
+uv run genelab [全局选项] <子命令> [参数]
+```
+
+## 子命令
+
+| 子命令 | 作用 |
+|--------|------|
+| `cache` | 创建项目本地仿真缓存目录（`.cache/`），并设置 `XDG_CACHE_HOME` / `MPLCONFIGDIR`。 |
+| `list robots` | 列出 `ROBOTS` 注册表里已注册的机器人。 |
+| `list envs` | 列出 `ENVS` 注册表里已注册的环境。 |
+| `list tasks` | 列出 `TASKS` 注册表里已注册的任务。 |
+| `play` | 在 Genesis 后端运行已注册任务，支持配置 override。 |
+| `train` | 任务带 RL runner 时启动训练，通过 `torchrun` 支持多 GPU。 |
+| `project new` | 生成一个新的下游扩展包骨架，三种注册表全部接通。 |
+
+## 全局选项
+
+放在任何子命令之前：
+
+- `--version` —— 打印 GeneLab 版本并退出。
+- `--import MODULE` —— 在派发子命令前显式导入一个扩展模块。可重复多次。适合扩展尚未提供
+  `genelab.extensions` entry point 时使用。
+- `--no-entry-points` —— 跳过通过 `genelab.extensions` entry-point 组的自动发现。
+  与 `--import` 搭配可实现完全显式、可复现的扩展加载。
+
+## 扩展加载顺序
+
+CLI 启动时按如下顺序发现扩展：
+
+1. **Entry points**：`genelab.extensions` 组的自动发现（除非加 `--no-entry-points`）。
+2. **显式 `--import MODULE`**：可多次。
+3. **程序内调用** `genelab.registry.load_extension_module(...)`（测试与嵌入脚本使用）。
+
+写下游扩展的详细方式见 [扩展加载](../concepts/extensions.md)。
+
+## 另见
+
+- [play 与 train](play-train.md) —— override 语法、多 GPU 训练、checkpoint。
+- [新建项目](project-new.md) —— 扩展包骨架生成。

docs/cli/play-train.en.md

@@ -0,0 +1,83 @@
+# Play and Train
+
+`play` and `train` share a common dispatch path: resolve `<task-id>` against the `TASKS` registry,
+construct its `TaskCfg`, apply any command-line overrides, and hand the configured task to either
+a single rollout (`play`) or the task's RL runner (`train`).
+
+## Play
+
+```bash
+uv run genelab play <task-id> [SHORT FLAGS] [-- OVERRIDES]
+```
+
+### Short flags
+
+These three short flags rewrite to the corresponding `env.scene.*` overrides:
+
+| Flag | Equivalent override | Effect |
+|------|--------------------|--------|
+| `--vis` | `env.scene.vis=true` | Enable Genesis visualization. |
+| `--gpu N` | `env.scene.gpu=N` | Pin the rollout to a single GPU index. |
+| `--steps N` | `env.scene.steps=N` | Cap episode length to `N` steps. |
+
+### Override grammar
+
+After the short flags, any `--<dotted.path> VALUE` argument is parsed as a config override:
+
+```bash
+uv run genelab play <task-id> \
+  --env.scene.dt 0.005 \
+  --env.actions.scale 0.5 \
+  --env.observations.include_velocity true
+```
+
+The dotted path walks the `TaskCfg` dataclass tree (typically rooted at `env.*`). Values are
+coerced from string using the field's type hint — `int`, `float`, `bool`, `Path`, `list[...]`,
+`tuple[...]` are all supported. See [Configs](../concepts/configs.md) for details on the coercion
+rules and how to handle unions and `Literal`.
+
+!!! tip "Flag ordering"
+    The CLI's `_normalize_run_flags` rewrites `play --steps 5 <task-id> ...` into
+    `play <task-id> --steps 5 ...` so that `argparse.REMAINDER` works. You can keep the short
+    flags before or after the task ID.
+
+## Train
+
+```bash
+uv run genelab train <task-id> [SHORT FLAGS] [-- OVERRIDES]
+```
+
+Train requires the registered task to expose an RL runner (commonly `rsl_rl_lib`). Override syntax
+is identical to `play`. Additional flags:
+
+| Flag | Effect |
+|------|--------|
+| `--gpus N` | Dispatch via `torchrun` for `N`-process distributed training. |
+| `--checkpoint PATH` | Resume training from a checkpoint file. |
+
+### Multi-GPU
+
+`--gpus N` wraps the underlying training entry point with `torchrun --standalone --nproc_per_node=N`.
+The task's runner must be `torchrun`-compatible; environments that depend on global Genesis state
+typically are.
+
+When `--gpus N` is set, the CLI also masks `CUDA_VISIBLE_DEVICES` to the requested devices so that
+each rank sees a distinct GPU.
+
+## Examples
+
+```bash
+# Quick local rollout with visualization.
+uv run genelab play wuji_hand --vis --steps 200
+
+# Train on 4 GPUs with a custom action scale.
+uv run genelab train wuji_hand --gpus 4 --env.actions.scale 0.3
+
+# Resume from a checkpoint.
+uv run genelab train wuji_hand --checkpoint logs/wuji_hand/run_42/model_100.pt
+```
+
+## See also
+
+- [Configs](../concepts/configs.md) — full `apply_overrides` semantics.
+- [Registry](../concepts/registry.md) — how tasks resolve from `<task-id>`.

docs/cli/play-train.zh.md

@@ -0,0 +1,78 @@
+# play 与 train
+
+`play` 与 `train` 共享同一条派发路径：在 `TASKS` 注册表查找 `<task-id>`，构造其 `TaskCfg`，
+应用命令行 override，然后交给单次 rollout（`play`）或任务自带的 RL runner（`train`）。
+
+## play
+
+```bash
+uv run genelab play <task-id> [短标志] [-- 覆盖项]
+```
+
+### 短标志
+
+这三个短标志会被改写为对应的 `env.scene.*` override：
+
+| 标志 | 等价 override | 作用 |
+|------|--------------|------|
+| `--vis` | `env.scene.vis=true` | 开启 Genesis 可视化。 |
+| `--gpu N` | `env.scene.gpu=N` | 把 rollout 锁定到指定 GPU。 |
+| `--steps N` | `env.scene.steps=N` | 限制 episode 步数。 |
+
+### Override 语法
+
+短标志之后的任意 `--<dotted.path> VALUE` 都会被当作配置 override：
+
+```bash
+uv run genelab play <task-id> \
+  --env.scene.dt 0.005 \
+  --env.actions.scale 0.5 \
+  --env.observations.include_velocity true
+```
+
+点路径会沿 `TaskCfg` 的 dataclass 树（通常以 `env.*` 为根）下钻。字符串值按目标字段类型注解
+自动转换 —— 支持 `int`、`float`、`bool`、`Path`、`list[...]`、`tuple[...]`。详细的转换规则
+和如何处理 union 与 `Literal` 见 [配置系统](../concepts/configs.md)。
+
+!!! tip "短标志位置"
+    CLI 内的 `_normalize_run_flags` 会把 `play --steps 5 <task-id> ...` 改写成
+    `play <task-id> --steps 5 ...`，让 `argparse.REMAINDER` 正常工作。短标志放在任务 ID 前后
+    都可以。
+
+## train
+
+```bash
+uv run genelab train <task-id> [短标志] [-- 覆盖项]
+```
+
+`train` 需要任务暴露一个 RL runner（通常是 `rsl_rl_lib`）。Override 语法与 `play` 一致。额外标志：
+
+| 标志 | 作用 |
+|------|------|
+| `--gpus N` | 通过 `torchrun` 启动 `N` 进程分布式训练。 |
+| `--checkpoint PATH` | 从 checkpoint 文件继续训练。 |
+
+### 多 GPU
+
+`--gpus N` 会把底层训练入口包装成 `torchrun --standalone --nproc_per_node=N`。任务自身的 runner
+必须支持 `torchrun`；依赖 Genesis 全局状态的环境通常天然兼容。
+
+设置 `--gpus N` 时 CLI 还会按所选设备掩码 `CUDA_VISIBLE_DEVICES`，让每个 rank 看到独立 GPU。
+
+## 示例
+
+```bash
+# 本地可视化跑一遍。
+uv run genelab play wuji_hand --vis --steps 200
+
+# 4 GPU 训练，并修改 action scale。
+uv run genelab train wuji_hand --gpus 4 --env.actions.scale 0.3
+
+# 从 checkpoint 继续。
+uv run genelab train wuji_hand --checkpoint logs/wuji_hand/run_42/model_100.pt
+```
+
+## 另见
+
+- [配置系统](../concepts/configs.md) —— `apply_overrides` 完整语义。
+- [注册表](../concepts/registry.md) —— `<task-id>` 如何解析。