[LeeLeno]

范围 / Scope

关联 #706，覆盖除已完成项外的全部子目标（P0×3 + P1×2 + P2×2）。按批次增量提交：

• f9c63ad P0：版本化站点 + 3 组参考页
• f3113e7 P1：两个 walkthrough + 训练诊断页 + 修过时引用
• 8ecd239 P2：docstring 基线 + interrogate 门槛 + changelog 纪律

站点版本化（参考 mjlab，仅 main）

• sphinx-multiversion 构建；分支白名单默认 ^(main)$，tag 白名单默认 ^$（不构建任何历史版本；未来发版用 SMV_TAG_WHITELIST 环境变量放行）
• Furo 侧栏版本切换下拉框（接口预留）
• 部署：fetch-depth: 0 → sphinx-multiversion → 根 redirect 到 main/en/0-index.html → keep_files: true（存量根目录页面保留，旧外链不死）；html_baseurl → /UniLab-doc/main/

P0 参考手册（双语）

• 5-reference/6-manager_terms/：reward/observation/termination term 参考表（框架级 unilab.envs.mdp 全部 29 个 + 任务层 locomotion/G1/motion tracking）
• 2-user_guide/5-domain_randomization/2-field_reference：14 个 DR event term 字段表 + 最小 owner YAML 示例 + FAQ（backend 适用性按 fail-closed + owner YAML 实证书写）
• 2-user_guide/2-algorithms/{ppo,appo,sac,flash_sac}：每页新增"配置参考"小节（训练效率/策略性能/training 段/reward 权重），默认值逐一核对 structured_configs.py

P1 walkthrough + 诊断（双语）

• 4-developer_guide/3-extending/5-onboard_new_robot：URDF/MJCF → import_robot → keyframe 检查单 → 最小 owner YAML → registry → 起训验证，每步带验证命令
• 4-developer_guide/3-extending/6-custom_reward：函数定义 → owner YAML 注入 → info["log"] 的 reward/<term> 验证 → 权重调整
• 2-user_guide/1-training/8-training_diagnostics：nan_guard → unilab-viz-nan 链路、info["log"] 字段、常见失败模式排查路径
• 修复过时引用：1-new_task.md 不再引用已删除的 go2/joystick.py；6-reward_porting.md 改用真实的 sensor_reward_terms.track_lin_vel 并去除过时的 NumPy 表述

P2 docstring 基线 + 纪律

• 9 个高优文件 docstring 补全至 100%（observations/managers types+manager_base/torch_env/reset_state/structured_configs/actions/curriculums/ray_observation）；全仓 interrogate 43.6% → 50.8%
• interrogate 入 dev 依赖（pyproject + pyproject.rocm + 双 lock 同步），fail-under = 40；CI ruff-lint job 新增检查步；make check-docstrings
• CONTRIBUTING.md 新增 Changelog Discipline（Unreleased 段、双语 Added/Changed/Fixed、issue 链接）；AGENTS.md 增加"新公开接口必须有 docstring"PR 要求
• changelog.md 顶部新增 ## Unreleased，收录本 PR 全部变更

与 issue 描述的偏差（issue 快照过时）

• HIM-PPO/HORA 已于 v1.2.0 移出本仓库，算法参考只覆盖 PPO/APPO/SAC/FlashSAC
• issue 中 base/np_env.py、go2/joystick.py、TensorResetRandomizationPayload 等路径/符号已不存在，按当前代码取证
• reward 权重字段实际为 reward.<term>.weight（非 *_scale）
• 子目标 7 的 changelog 内容部分现状已达标，本 PR 只补纪律与 Unreleased 段

验证 / Validation

• uv run pytest tests/scripts/test_check_docs.py -q → 20 passed
• make check（ruff format/check + mypy + pyright）→ 通过（22 条 missing-optional-import 为既有警告）
• uv run pytest tests/test_library_import_boundary.py -q → 28 passed（lazy-import 边界完整）
• uv run interrogate src/unilab → PASSED（min 40.0%, actual 50.8%）
• plain sphinx-build -n 与 sphinx-multiversion 构建均成功，新增页面零 warning（存量 13 条为既有问题）；多版本构建仅产出 main/ 目录，版本切换器渲染正常
• 本地 intersphinx 外网不可达用 -D intersphinx_timeout=30 跳过（仅影响外部交叉引用，CI 不受影响）；walkthrough 中需 GPU/backend/显示器的步骤已在文中标注，未实机验证

遗留 / Follow-ups

• 启用多版本前需把 html_baseurl 按版本动态化（conf.py/README 已注明）
• interrogate 门槛 40% 为起步值，后续可逐步提高