Repository navigation
docs(sphinx): optimize content, add language switcher - #516
Merged
Merged
Conversation
Major documentation quality pass following the bilingual restructure: Language switcher ----------------- - Add _templates/language_switcher.html with JS-based path swap - Inject switcher into every page via conf.py html-page-context hook - Add CSS styling for the dropdown in custom.css - Simplify root index.md to work with the site-level switcher Content fixes ------------- - Remove all 27 stale path references (docs/users/, docs/developers/, ../../README.md) from sphinx source pages - Fix glossary.md Related Documents links to use new paths - Deduplicate installation.md vs quickstart.md (now distinct content) - Remove hand-written ## Navigation / Previous / Next from all English pages (Furo provides this via toctree order) - Slim en/index.md from 417 → 133 lines (move arch diagram and tables into appropriate sub-pages) Skeleton fill ------------- - Fill 30 of 33 English skeleton pages with real content derived from code ground truth and zh_CN translations - Remaining 3 thin pages (configuration_overrides, scene_export, nan_visualizer) have basic structure but await deeper content Test & validation ----------------- - Update doc_checks.py: add check for stale README back-links and English navigation blocks - Add 3 new test cases in test_check_docs.py (22 total, all pass) - sphinx-build exit 0 with only 1 warning (Hydra intersphinx 404, external issue) Also updates: - AGENTS.md rewritten to reflect navigation rules and link patterns - ADR files: fix Navigation back-links - zh_CN files: fix stale docs/users/ references in prose - conf.py: remove announcement banner, add language context injection Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Sphinx documentation site to support bilingual navigation and modernizes/normalizes the MyST/Sphinx source tree, with new automated checks to prevent regressions in link patterns and English-page navigation conventions.
Changes:
- Adds a site-wide language switcher (Sphinx
html-page-contextinjection + template + CSS) and refreshes the root landing language picker. - Introduces doc “warning” checks to flag removed legacy paths and disallowed English manual navigation blocks, and enforces warnings-free docs in CI.
- Performs broad doc content and link refactors across EN/ZH pages (moving toward
{doc}roles and updated doc structure).
Reviewed changes
Copilot reviewed 76 out of 76 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/scripts/test_check_docs.py | Asserts both doc errors and doc warnings are empty; adds focused tests for migration-guard warnings. |
| tests/scripts/doc_checks.py | Adds removed-path warning patterns, EN-page guard checks, and warning collection API. |
| docs/sphinx/source/conf.py | Injects language switcher into HTML pages and adds helper logic for language target resolution. |
| docs/sphinx/source/_templates/language_switcher.html | Adds the switcher HTML + JS redirect behavior. |
| docs/sphinx/source/_static/css/custom.css | Styles language switcher + landing picker; adds responsive layout tweaks. |
| docs/sphinx/source/index.md | Replaces button-based language landing with a dropdown language picker + JS redirect. |
| docs/sphinx/source/en/index.md | Slims and restructures the EN landing page and consolidates toctree/navigation. |
| docs/sphinx/source/changelog.md | Updates changelog notes describing the bilingual Sphinx source layout and shared pages. |
| docs/sphinx/source/glossary.md | Updates related-doc links to {doc} targets with new Sphinx paths. |
| docs/sphinx/source/adr/README.md | Updates ADR links to {doc} and root /index doc target. |
| docs/sphinx/source/adr/ADR-TEMPLATE.md | Updates template related-doc links to {doc} targets. |
| docs/sphinx/source/adr/ADR-0000-index.md | Updates links to {doc} targets and root /index. |
| docs/sphinx/source/adr/ADR-0001-runtime-model-and-layer-boundaries.md | Updates related-doc links to {doc} targets and new doc paths. |
| docs/sphinx/source/adr/ADR-0002-backend-capability-boundary-for-play-and-snapshot.md | Updates related-doc links to {doc} targets and new doc paths. |
| docs/sphinx/source/adr/ADR-0003-task-owner-and-config-compose-contract.md | Updates evidence/related links to new Sphinx source locations. |
| docs/sphinx/source/adr/ADR-0004-registry-bootstrap-contract.md | Updates related-doc links to {doc} targets and new doc paths. |
| docs/sphinx/source/adr/ADR-0005-unified-obs-critic-env-and-ipc-contract.md | Updates related-doc links to {doc} targets and new doc paths. |
| docs/sphinx/source/en/agents/index.md | Replaces EN agent placeholder with a concise repo-facts quick reference. |
| docs/sphinx/source/en/user_guide/tooling/wandb_and_tensorboard.md | Expands EN tooling guidance with config keys and script examples. |
| docs/sphinx/source/en/user_guide/tooling/scene_export.md | Updates EN tooling text to point to current export + env-visualization paths. |
| docs/sphinx/source/en/user_guide/tooling/onnx_export.md | Adds concrete ONNX export guidance and script-level examples. |
| docs/sphinx/source/en/user_guide/tooling/nan_visualizer.md | Documents NaN guard config and ties it to the console tool + tests. |
| docs/sphinx/source/en/user_guide/terrain/heightfield_import.md | Expands EN terrain import notes with “files to read” and smoke commands. |
| docs/sphinx/source/en/user_guide/terrain/procedural.md | Refactors terrain page content and removes manual navigation block. |
| docs/sphinx/source/en/user_guide/tasks/locomotion_zoo.md | Expands task overview with runnable owner examples and support-matrix pointer. |
| docs/sphinx/source/en/user_guide/tasks/manipulation_zoo.md | Expands task overview with owner paths and runnable commands. |
| docs/sphinx/source/en/user_guide/tasks/go2_arm_manip_loco.md | Removes language tag and manual navigation; retains task entry content. |
| docs/sphinx/source/en/user_guide/tasks/g1_motion_tracking.md | Removes language tag and manual navigation; updates one repo path reference. |
| docs/sphinx/source/en/user_guide/manipulation/manip_loco.md | Adds concrete PPO/HIM-PPO owner paths and commands for manip-loco. |
| docs/sphinx/source/en/user_guide/manipulation/dexterous_inhand.md | Removes language tag and manual navigation; keeps in-hand training instructions. |
| docs/sphinx/source/en/user_guide/getting_started/installation.md | Deduplicates from quickstart and rewrites as EN-focused dependency/setup doc. |
| docs/sphinx/source/en/user_guide/getting_started/quickstart.md | Removes language tag/manual nav and updates some intra-doc links. |
| docs/sphinx/source/en/user_guide/getting_started/training.md | Removes language tag/manual nav and updates one doc-role link. |
| docs/sphinx/source/en/user_guide/backends/mujoco.md | Rewrites EN backend overview with commands and codebase pointers. |
| docs/sphinx/source/en/user_guide/backends/motrix.md | Rewrites EN backend overview with setup, usage guidance, and commands. |
| docs/sphinx/source/en/user_guide/backends/choosing_a_backend.md | Replaces old table with owner-based selection rules + examples. |
| docs/sphinx/source/en/user_guide/backends/index.md | Updates ADR links to {doc} targets and removes manual nav block. |
| docs/sphinx/source/en/user_guide/algorithms/appo.md | Fills EN APPO page with scripts/config references and common overrides. |
| docs/sphinx/source/en/user_guide/algorithms/ppo.md | Fills EN PPO page with scripts/config references and common overrides. |
| docs/sphinx/source/en/user_guide/algorithms/mlx_ppo.md | Fills EN MLX PPO page with entrypoints/config and notes. |
| docs/sphinx/source/en/user_guide/algorithms/fast_sac.md | Fills EN FastSAC page with script/config defaults and constraints. |
| docs/sphinx/source/en/user_guide/algorithms/fast_td3.md | Fills EN FastTD3 page with script/config defaults and guidance. |
| docs/sphinx/source/en/user_guide/algorithms/flash_sac.md | Fills EN FlashSAC page with selection rules and constraints. |
| docs/sphinx/source/en/user_guide/algorithms/him_ppo.md | Fills EN HIM-PPO page with owner details and playback examples. |
| docs/sphinx/source/en/user_guide/algorithms/hora.md | Fills EN HORA page describing teacher + distillation flows. |
| docs/sphinx/source/en/user_guide/algorithms/overview.md | Updates the algorithm overview and removes manual nav block. |
| docs/sphinx/source/en/user_guide/domain_randomization/index.md | Refactors DR overview and updates contract link to new {doc} target. |
| docs/sphinx/source/en/user_guide/domain_randomization/recipes.md | Adds practical DR recipes and codebase pointers. |
| docs/sphinx/source/en/transfer/sim_to_sim/playback_and_snapshot_differences.md | Updates ADR link to an absolute {doc} target. |
| docs/sphinx/source/en/transfer/sim_to_sim/owner_yaml_swap.md | Updates glossary link to an absolute {doc} target. |
| docs/sphinx/source/en/transfer/sim_to_sim/known_capability_gaps.md | Updates changelog link to an absolute {doc} target. |
| docs/sphinx/source/en/developer_guide/contributing.md | Updates doc links to new {doc} targets and removes manual nav block. |
| docs/sphinx/source/en/developer_guide/contributing_workflow.md | Updates doc links to new {doc} targets and removes manual nav block. |
| docs/sphinx/source/en/developer_guide/contracts/env_contract.md | Rewrites EN contract page with rules and code-evidence pointers. |
| docs/sphinx/source/en/developer_guide/contracts/backend_capability.md | Rewrites EN contract page with explicit interface/capability guidance. |
| docs/sphinx/source/en/developer_guide/contracts/runner_lifecycle.md | Rewrites EN lifecycle page with script/runner boundaries + evidence pointers. |
| docs/sphinx/source/en/developer_guide/contracts/task_owner_config.md | Rewrites EN owner-YAML contract description + evidence pointers. |
| docs/sphinx/source/en/developer_guide/contracts/domain_randomization.md | Updates cross-linking to user DR page and ADR/dev-standard references. |
| docs/sphinx/source/en/developer_guide/architecture/layer_boundaries.md | Adds English checklist aligned to ADR-0001 + evidence pointers. |
| docs/sphinx/source/en/developer_guide/architecture/runtime_model.md | Rewrites runtime model overview with sync vs async runner shapes. |
| docs/sphinx/source/en/developer_guide/architecture/registry_bootstrap.md | Documents registry bootstrap runtime flow + extension rules + evidence. |
| docs/sphinx/source/en/developer_guide/architecture/scene_composition.md | Updates rough-terrain doc link and removes manual navigation block. |
| docs/sphinx/source/en/developer_guide/architecture/development_standard.md | Updates glossary and ADR links to {doc} targets. |
| docs/sphinx/source/en/developer_guide/extending/new_algorithm.md | Replaces stub with a concrete integration checklist and validations. |
| docs/sphinx/source/en/developer_guide/extending/new_backend.md | Replaces stub with backend-shape checklist and validations. |
| docs/sphinx/source/en/developer_guide/extending/new_task.md | Replaces stub with task checklist and validations/evidence. |
| docs/sphinx/source/en/developer_guide/extending/new_terrain.md | Replaces stub with terrain checklist and validations/evidence. |
| docs/sphinx/source/zh_CN/user_guide/D-tasks/02-g1-motion-tracking.md | Replaces legacy link with {doc} to the new developer guide path. |
| docs/sphinx/source/zh_CN/user_guide/05-domain-randomization.md | Updates a developer-doc link to {doc} while keeping ZH navigation section. |
| docs/sphinx/source/zh_CN/developer_guide/scene-composition-design.md | Updates legacy user-doc links to new {doc} targets. |
| docs/sphinx/source/zh_CN/developer_guide/domain-randomization-contract.md | Updates user-doc and ADR links to {doc} and removes a raw source-link bullet. |
| docs/sphinx/source/zh_CN/developer_guide/development-standard.md | Converts glossary/ADR related-doc links to {doc} targets. |
| docs/sphinx/source/zh_CN/developer_guide/CONTRIBUTING.md | Updates stale paths to new Sphinx tree and replaces legacy doc links with {doc}. |
| docs/sphinx/source/zh_CN/developer_guide/collaboration.md | Converts related-document links to {doc} targets. |
| docs/sphinx/source/zh_CN/agents/01-agent-quick-reference.md | Converts legacy doc links to {doc} and removes a hard relative link to AGENTS. |
| docs/sphinx/AGENTS.md | Updates agent-writing rules for the new bilingual structure, link patterns, and navigation conventions. |
Comments suppressed due to low confidence (3)
docs/sphinx/source/en/user_guide/getting_started/quickstart.md:9
- This page is under
source/en/but is written in Chinese. For the bilingual site to work as intended, English pages should be in English (or be explicit placeholders) and the Chinese version should live undersource/zh_CN/.
docs/sphinx/source/en/user_guide/getting_started/training.md:8 - This page is under
source/en/but the content is still Chinese. Please translate it to English (or replace with an English placeholder that links to the Chinese version) so the/en/tree is consistently English.
docs/sphinx/source/en/user_guide/backends/index.md:8 - This page is located under
source/en/but is written in Chinese (including the heading). Please translate it to English or move it underzh_CN/and keep an English version here, otherwise the English navigation lands users on Chinese content.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
1
to
9
| @@ -9,19 +8,19 @@ | |||
| 3. 想改子地形组合时，正确的入口是什么？ | |||
| 4. 哪些是当前已知的边界，不是 bug 而是约束？ | |||
Comment on lines
11
to
12
| 底层 contract（cold-path materialization、注册新 sub-terrain、hfield 导出）见 `base/backend/mujoco/xml.py`、`base/backend/motrix/scene.py` 与 `terrains/terrain_generator.py` 的源码注释。 | ||
|
|
Comment on lines
1
to
5
| # 算法 | ||
|
|
||
| 语言: 简体中文 | ||
|
|
||
| 本页只保留算法级说明。入口脚本和通用 CLI 参数见 [Training Guide](03-training.md)。 | ||
| 本页只保留算法级说明。入口脚本和通用 CLI 参数见 {doc}`Training Guide <../getting_started/training>`。 | ||
|
|
Comment on lines
1
to
7
| # 域随机化现状 | ||
|
|
||
| 语言: 简体中文 | ||
|
|
||
| 这页只描述当前仓库里已经注册、且已经接入 DR provider 的任务现状。结论全部来自代码，不按设计意图推断。 | ||
|
|
||
| 当前统一入口在 [`NpEnv._init_domain_randomization()`](../../../src/unilab/base/np_env.py) 和 [`DomainRandomizationManager`](../../../src/unilab/dr/manager.py)： | ||
| 当前统一入口在 `NpEnv._init_domain_randomization()` 和 `DomainRandomizationManager`： | ||
|
|
Comment on lines
1
to
7
| # 协作流程 | ||
|
|
||
| 语言: 简体中文 | ||
|
|
||
| 仓库文档只记录稳定标准。执行状态、owner 和阶段推进应放在 GitHub 协作对象中。 | ||
|
|
||
| 如果你只是想安装或训练 UniLab，请先看 `README.md`、`docs/users/zh_CN/01-getting-started.md` 和 `docs/users/zh_CN/03-training.md`。 | ||
| 如果你只是想安装或训练 UniLab，请先看 {doc}`/en/user_guide/getting_started/installation` 和 {doc}`/en/user_guide/getting_started/training`。 | ||
|
|
Comment on lines
+267
to
+277
| def _language_target(app, pagename: str, language_code: str) -> str: | ||
| found_docs = app.env.found_docs | ||
| current_language = _page_language(pagename) | ||
|
|
||
| if current_language in _LANGUAGE_DOC_ROOTS: | ||
| _, _, rest = pagename.partition("/") | ||
| candidate = f"{language_code}/{rest}" if rest else f"{language_code}/index" | ||
| if candidate in found_docs: | ||
| return candidate | ||
|
|
||
| return f"{language_code}/index" |
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1. Translate 4 English doc pages that were still in Chinese: - en/user_guide/terrain/procedural.md → "Procedural Terrain" - en/user_guide/algorithms/overview.md → "Algorithms" - en/user_guide/domain_randomization/index.md → "Domain Randomization Status" - en/developer_guide/contributing_workflow.md → "Collaboration Workflow" File path references in procedural.md normalized to src/unilab/... form so readers can locate the cited code (per Copilot feedback). 2. conf.py: add explicit zh_CN ↔ en path map for the language switcher. The zh_CN tree keeps legacy numbered paths (01-getting-started.md, A-getting-started/, C-algorithms/) that don't 1:1 mirror the English semantic paths. The new _LANGUAGE_PATH_FORWARD table makes the switcher land on the closest equivalent page instead of bouncing to the language index. Both directions are populated automatically. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
Thanks for the review. Addressed in commits
Validation:
|
TATP-233
pushed a commit
that referenced
this pull request
May 30, 2026
1. Translate 4 English doc pages that were still in Chinese: - en/user_guide/terrain/procedural.md → "Procedural Terrain" - en/user_guide/algorithms/overview.md → "Algorithms" - en/user_guide/domain_randomization/index.md → "Domain Randomization Status" - en/developer_guide/contributing_workflow.md → "Collaboration Workflow" File path references in procedural.md normalized to src/unilab/... form so readers can locate the cited code (per Copilot feedback). 2. conf.py: add explicit zh_CN ↔ en path map for the language switcher. The zh_CN tree keeps legacy numbered paths (01-getting-started.md, A-getting-started/, C-algorithms/) that don't 1:1 mirror the English semantic paths. The new _LANGUAGE_PATH_FORWARD table makes the switcher land on the closest equivalent page instead of bouncing to the language index. Both directions are populated automatically. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TATP-233
added a commit
that referenced
this pull request
May 30, 2026
docs(sphinx): optimize content, add language switcher
TATP-233
pushed a commit
that referenced
this pull request
May 30, 2026
1. Translate 4 English doc pages that were still in Chinese: - en/user_guide/terrain/procedural.md → "Procedural Terrain" - en/user_guide/algorithms/overview.md → "Algorithms" - en/user_guide/domain_randomization/index.md → "Domain Randomization Status" - en/developer_guide/contributing_workflow.md → "Collaboration Workflow" File path references in procedural.md normalized to src/unilab/... form so readers can locate the cited code (per Copilot feedback). 2. conf.py: add explicit zh_CN ↔ en path map for the language switcher. The zh_CN tree keeps legacy numbered paths (01-getting-started.md, A-getting-started/, C-algorithms/) that don't 1:1 mirror the English semantic paths. The new _LANGUAGE_PATH_FORWARD table makes the switcher land on the closest equivalent page instead of bouncing to the language index. Both directions are populated automatically. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TATP-233
added a commit
that referenced
this pull request
May 30, 2026
docs(sphinx): optimize content, add language switcher
TATP-233
pushed a commit
that referenced
this pull request
Sep 4, 2026
1. Translate 4 English doc pages that were still in Chinese: - en/user_guide/terrain/procedural.md → "Procedural Terrain" - en/user_guide/algorithms/overview.md → "Algorithms" - en/user_guide/domain_randomization/index.md → "Domain Randomization Status" - en/developer_guide/contributing_workflow.md → "Collaboration Workflow" File path references in procedural.md normalized to src/unilab/... form so readers can locate the cited code (per Copilot feedback). 2. conf.py: add explicit zh_CN ↔ en path map for the language switcher. The zh_CN tree keeps legacy numbered paths (01-getting-started.md, A-getting-started/, C-algorithms/) that don't 1:1 mirror the English semantic paths. The new _LANGUAGE_PATH_FORWARD table makes the switcher land on the closest equivalent page instead of bouncing to the language index. Both directions are populated automatically. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TATP-233
added a commit
that referenced
this pull request
Sep 4, 2026
docs(sphinx): optimize content, add language switcher
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/users/,docs/developers/,../../README.md) inside the Sphinx source treeinstallation.md/quickstart.md(were byte-for-byte identical, now distinct)## Navigation/Previous/Nextblocks from all English pages (rely on Furo's built-in toctree navigation)en/index.mdfrom 417 → 133 lines (move architecture diagram and tables into sub-pages)AGENTS.mdto reflect new navigation rules, link patterns, and anti-patternsChanges by area
_templates/language_switcher.html,conf.py,custom.css{doc}roles or correct relative pathsinstallation.md,quickstart.mden/index.md,index.mddoc_checks.py,test_check_docs.pyTest plan
uv run pytest tests/scripts/test_check_docs.py -q→ 22 passedcollect_doc_errors()→ 0 errorssphinx-build -b html -n source build/html→ exit 0, 1 warning (Hydra intersphinx 404, external)/en/and/zh_CN/🤖 Generated with Claude Code