Restructure documentation

docs/api/reference.md

@@ -1,43 +1,102 @@
+---
+search:
+  exclude: true
+---
+
 # 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.
+This page is generated from source docstrings via
+[`mkdocstrings`](https://mkdocstrings.github.io/). It is shared by both language versions of the
+site. Concept and how-to pages explain how to use the APIs; this page is for signatures, members,
+and defaults.
 
-!!! note "Single-source"
-    The API reference is generated from English docstrings and is shared by both language
-    versions of this site.
+## Public facade
 
----
+::: genelab.lab
+    options:
+      show_if_no_docstring: true
 
-## `genelab.lab`
+## Registries and configs
 
-The public facade. Most user code should import from here rather than from `genelab.registry`
-directly.
+::: genelab.registry
+    options:
+      show_if_no_docstring: true
 
-::: genelab.lab
+::: genelab.configs
     options:
       show_if_no_docstring: true
 
----
+## Environment
 
-## `genelab.registry`
+::: genelab.envs.manager_based_rl_env
+    options:
+      show_if_no_docstring: true
 
-::: genelab.registry
+## Managers
+
+::: genelab.managers
     options:
       show_if_no_docstring: true
 
----
+## MDP library
 
-## `genelab.configs`
+::: genelab.mdp
+    options:
+      show_if_no_docstring: true
 
-::: genelab.configs
+## Scene and entities
+
+::: genelab.scene
     options:
       show_if_no_docstring: true
 
----
+::: genelab.entity
+    options:
+      show_if_no_docstring: true
+
+## Actuators
+
+::: genelab.actuator
+    options:
+      show_if_no_docstring: true
+
+## Sensors
+
+::: genelab.sensor
+    options:
+      show_if_no_docstring: true
+
+## Terrains
+
+::: genelab.terrains
+    options:
+      show_if_no_docstring: true
+
+## RL
+
+::: genelab.rl
+    options:
+      show_if_no_docstring: true
+
+## Recording
+
+::: genelab.recording
+    options:
+      show_if_no_docstring: true
+
+## Bridges
+
+::: genelab.bridges
+    options:
+      show_if_no_docstring: true
+
+## Asset zoo
+
+::: genelab.asset_zoo
+    options:
+      show_if_no_docstring: true
 
-## `genelab.cache`
+## Utilities
 
 ::: genelab.cache
     options:

docs/best-practices/debugging.en.md

@@ -0,0 +1,88 @@
+# How to Debug Common Failures
+
+This guide lists the shortest checks for common GeneLab failures.
+
+## Unknown task
+
+```bash
+uv run genelab list tasks
+uv run genelab --import my_project.tasks list tasks
+```
+
+If the second command works, the package is importable only when you pass `--import`. Install an
+entry point or keep using an explicit import. If neither works, confirm the package is installed or
+its `src/` directory is on `PYTHONPATH`.
+
+## Unknown override path
+
+```bash
+uv run genelab info TASK_ID
+```
+
+Copy the path from `Overridable cfg paths`. Remember that `play` shortcuts may retarget
+`env.simulation.*` to `play_env.simulation.*` when a task has `play_env`.
+
+## Torch or Genesis import errors
+
+```bash
+uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
+uv run python -c "import genesis; print(genesis.__version__)"
+```
+
+Pick exactly one `torch-*` extra and resync if needed:
+
+```bash
+uv sync --reinstall-package torch --extra torch-cu128
+```
+
+## Cache or write-location errors
+
+```bash
+uv run genelab cache
+```
+
+This creates project-local cache directories and points `XDG_CACHE_HOME` and `MPLCONFIGDIR` at
+`.cache/`.
+
+## Viewer failures
+
+First run headless:
+
+```bash
+uv run genelab play TASK_ID --steps 32
+```
+
+Then try viewer mode:
+
+```bash
+uv run genelab play TASK_ID --vis --steps 128
+```
+
+Viewer failures are usually graphics-driver, display, or OpenGL platform problems rather than
+registry problems.
+
+## Observation or reward shape errors
+
+Manager terms should return batch-shaped tensors:
+
+| Term type | Expected shape |
+|---|---|
+| observation term | `(num_envs, d)` or `(num_envs,)` |
+| reward term | `(num_envs,)` |
+| termination term | `(num_envs,)` bool |
+
+Avoid scalar `()` tensors. They can broadcast incorrectly or fail later in the runner.
+
+## Distributed env-count errors
+
+`--num_envs` is total across ranks and must divide evenly by `--gpus`.
+
+```bash
+uv run genelab train TASK_ID --gpus 4 --num_envs 4096
+```
+
+Use `--num_envs_per_gpu` to avoid division:
+
+```bash
+uv run genelab train TASK_ID --gpus 4 --num_envs_per_gpu 1024
+```

docs/best-practices/debugging.zh.md

@@ -0,0 +1,85 @@
+# 如何调试常见问题
+
+这份指南列出 GeneLab 常见失败的最短排查路径。
+
+## Unknown task
+
+```bash
+uv run genelab list tasks
+uv run genelab --import my_project.tasks list tasks
+```
+
+如果第二条命令能看到任务，说明包只有在显式 `--import` 时才被导入。安装 entry point，
+或继续使用显式导入。如果两条都不行，确认包已安装，或它的 `src/` 目录在 `PYTHONPATH` 上。
+
+## Unknown override path
+
+```bash
+uv run genelab info TASK_ID
+```
+
+从 `Overridable cfg paths` 复制路径。注意 task 有 `play_env` 时，`play` 的短标志可能把
+`env.simulation.*` 重定向到 `play_env.simulation.*`。
+
+## Torch 或 Genesis 导入错误
+
+```bash
+uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
+uv run python -c "import genesis; print(genesis.__version__)"
+```
+
+只选择一个 `torch-*` extra。需要时重新同步：
+
+```bash
+uv sync --reinstall-package torch --extra torch-cu128
+```
+
+## 缓存或写入目录错误
+
+```bash
+uv run genelab cache
+```
+
+这会创建项目本地缓存目录，并把 `XDG_CACHE_HOME` 和 `MPLCONFIGDIR` 指向 `.cache/`。
+
+## Viewer 失败
+
+先无界面运行：
+
+```bash
+uv run genelab play TASK_ID --steps 32
+```
+
+再尝试 viewer：
+
+```bash
+uv run genelab play TASK_ID --vis --steps 128
+```
+
+viewer 失败通常是图形驱动、display 或 OpenGL platform 问题，而不是注册表问题。
+
+## Observation 或 reward shape 错误
+
+Manager term 应返回带 batch 维度的 tensor：
+
+| Term 类型 | 期望 shape |
+|---|---|
+| observation term | `(num_envs, d)` 或 `(num_envs,)` |
+| reward term | `(num_envs,)` |
+| termination term | `(num_envs,)` bool |
+
+避免返回标量 `()` tensor。它可能错误广播，或在 runner 中延迟失败。
+
+## 分布式 env 数错误
+
+`--num_envs` 表示所有 rank 的总数，必须能被 `--gpus` 整除。
+
+```bash
+uv run genelab train TASK_ID --gpus 4 --num_envs 4096
+```
+
+想避免除法语义时使用 `--num_envs_per_gpu`：
+
+```bash
+uv run genelab train TASK_ID --gpus 4 --num_envs_per_gpu 1024
+```

docs/best-practices/extension-projects.en.md

@@ -0,0 +1,91 @@
+# How to Build an Extension Project
+
+Use an extension project when your robot, task, or experiment should live outside `src/genelab/`.
+This is the normal shape for downstream research code.
+
+## 1. Generate a scaffold
+
+```bash
+uv run genelab project new my_robot_project
+```
+
+The generated package has:
+
+```text
+my_robot_project/
+├── pyproject.toml
+└── src/my_robot_project/
+    ├── config.py
+    ├── envs.py
+    ├── robots.py
+    └── tasks.py
+```
+
+## 2. Keep responsibilities separate
+
+| File | Responsibility |
+|---|---|
+| `config.py` | Dataclasses owned by the project. |
+| `robots.py` | Robot asset/config factories. |
+| `envs.py` | Runtime env classes or env factory helpers. |
+| `tasks.py` | `register()` hook and task classes. |
+
+Avoid importing Genesis at module import time unless the object truly needs it. Registry discovery
+should stay cheap.
+
+## 3. Register through one hook
+
+Expose a no-argument `register()` function:
+
+```python
+def register() -> None:
+    register_robot(...)
+    register_env(...)
+    register_task(...)
+```
+
+Guard repeated registration when the hook may run more than once:
+
+```python
+if "my-robot" not in ROBOTS:
+    register_robot(...)
+```
+
+## 4. Prefer entry points for daily use
+
+In `pyproject.toml`:
+
+```toml
+[project.entry-points."genelab.extensions"]
+my_robot_project = "my_robot_project.tasks:register"
+```
+
+Then install as editable:
+
+```bash
+uv pip install -e my_robot_project
+uv run genelab list tasks
+```
+
+Use explicit imports for temporary experiments:
+
+```bash
+PYTHONPATH=my_robot_project/src \
+  uv run genelab --import my_robot_project.tasks list tasks
+```
+
+## 5. Verify the package boundary
+
+Run these from outside the package directory:
+
+```bash
+uv run python -c "import my_robot_project"
+uv run genelab list tasks
+uv run genelab info MyProject-Example-v0
+uv run genelab play MyProject-Example-v0 --steps 3
+```
+
+## Expected result
+
+The project can be imported as a normal Python package, GeneLab discovers its entry point, and all
+task commands work without editing GeneLab core.