[RFC] Q3 2026 Refactoring Guide

[zheliuyu]

Summary

The docs site previously embedded community Ascend/NPU documentation via git submodules + copy-docs, then built them locally. As upstream projects now maintain their own doc sites, this approach adds maintenance cost, build fragility, and stale content.

Proposal (implemented): stop local compilation for projects with official doc sites; link to them from homepage cards and lightweight sidebar placeholder pages. Build flow is reduced to fetch-config → sphinx-build.

---

Problem

Before:

git submodule update → copy-docs → sync-onnxruntime-doc → sphinx-build

7 submodules (verl, LLaMA-Factory, ms-swift, VeOmni, vllm-ascend, triton-ascend, deepspeed) plus ONNX Runtime doc sync.

Pain points:

• High maintenance: submodule versions, per-project copy rules, custom sidebars (layout.html, independent_communities)
• Unstable CI: submodule fetch failures, OOM from duplicate _repos + sources/_generated content
• Stale docs: local copies lag behind upstream

Opportunity: all affected projects now host Ascend/NPU docs on official sites (Read the Docs, project docs, etc.).

---

Solution

Navigation model

Layer	Behavior
Homepage cards	External links to GitHub / docs / Ascend guides (target="_blank")
Sidebar	Lightweight sources/<project>/index.rst placeholder pages
Placeholder page	Short intro + links to official docs

Build

- html: fetch-config + copy-docs + sync-onnxruntime-doc + sphinx-build
+ html: fetch-config + sphinx-build

CI: remove submodules: true.

Affected projects

verl, LLaMA-Factory, ms-swift, VeOmni, vLLM-Ascend, Triton-Ascend, DeepSpeed, ONNX Runtime (quick start only).

Unchanged: projects still maintained locally (accelerate, trl, pytorch, sglang, etc.).

---

Key changes

Removed: .gitmodules, _repos/*, copy-docs / init-submodules / sync-onnxruntime-doc, layout.html, independent-sidebar CSS/JS, sources/_generated/

Updated: homepage cards → external links; sources/*/index.rst → short placeholder pages; README.md, .gitignore, conf.py

Net: ~1,100 lines removed; make html passes.

---

Trade-offs

Benefit	Cost
Faster, lighter builds	Users leave the docs site
Always up-to-date upstream content	No offline mirror of community docs
Less maintenance	Site search no longer covers community docs
Simpler codebase	External link rot if upstream URLs change

---

Adding a new external-link project

1. Create sources/<project>/index.rst with official doc links
2. Update the homepage card in index.rst to point externally
3. Add the entry to the hidden toctree in index.rst

No Makefile changes required.

---

Open questions

1. Triton-Ascend GitHub URL: gitcode.com → github.com/triton-lang/triton-ascend — align with community migration?
2. Add target="_blank" to all homepage cards for consistency?
3. CI link health checks for external URLs?
4. Fallback if an upstream doc site goes down?

---

References

• PR / Commit: [refactor] drop doc submodules, link community docs to official sites #136