From 08b340cbb15786a32845b6ba8e150c110250a65e Mon Sep 17 00:00:00 2001 From: root <15750543867@163.com> Date: Wed, 12 Aug 2026 15:15:24 +0800 Subject: [PATCH 1/2] refactor: drop doc submodules, link community docs to official sites --- .github/workflows/gh-pages.yml | 3 - .gitignore | 3 - .gitmodules | 28 ---- Makefile | 94 +------------ README.md | 12 +- _repos/LLaMA-Factory | 1 - _repos/VeOmni | 1 - _repos/deepspeed | 1 - _repos/ms-swift | 1 - _repos/triton-ascend | 1 - _repos/verl | 1 - _repos/vllm-ascend | 1 - _static/custom.css | 72 ---------- _static/llamafactory_actions.js | 49 ------- _static/onnxruntime_quickstart.js | 14 -- _templates/layout.html | 125 ------------------ conf.py | 128 +++--------------- index.rst | 33 +++-- sources/LLaMA-Factory/index.rst | 10 +- sources/VeOmni/index.rst | 11 +- sources/deepspeed/index.rst | 9 +- sources/ms-swift/index.rst | 10 +- sources/onnxruntime/index.rst | 1 - sources/triton-ascend/index.rst | 211 +----------------------------- sources/verl/index.rst | 207 +---------------------------- sources/vllm-ascend/index.rst | 179 +------------------------ 26 files changed, 73 insertions(+), 1133 deletions(-) delete mode 100644 .gitmodules delete mode 160000 _repos/LLaMA-Factory delete mode 160000 _repos/VeOmni delete mode 160000 _repos/deepspeed delete mode 160000 _repos/ms-swift delete mode 160000 _repos/triton-ascend delete mode 160000 _repos/verl delete mode 160000 _repos/vllm-ascend delete mode 100644 _static/llamafactory_actions.js delete mode 100644 _static/onnxruntime_quickstart.js delete mode 100644 _templates/layout.html diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index c0534a7c..65275eeb 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -20,9 +20,6 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - with: - submodules: true - fetch-depth: 0 - uses: actions/setup-python@v5 with: diff --git a/.gitignore b/.gitignore index c4f7724b..a75164dd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,9 +3,6 @@ _build/* .vscode .DS_Store sources/pytorch/api_doc.rst -sources/_generated_static/ascend_config.json -sources/_generated/ .tasks/ venv/ -_repos/ _static/ascend_config.json diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 1762cbd2..00000000 --- a/.gitmodules +++ /dev/null @@ -1,28 +0,0 @@ -[submodule "_repos/verl"] - path = _repos/verl - url = https://github.com/volcengine/verl.git - branch = main -[submodule "_repos/LLaMA-Factory"] - path = _repos/LLaMA-Factory - url = https://github.com/the-seeds/LLaMA-Factory-Doc.git - branch = main -[submodule "_repos/VeOmni"] - path = _repos/VeOmni - url = https://github.com/ByteDance-Seed/VeOmni.git - branch = main -[submodule "_repos/ms-swift"] - path = _repos/ms-swift - url = https://github.com/modelscope/ms-swift.git - branch = main -[submodule "_repos/vllm-ascend"] - path = _repos/vllm-ascend - url = https://github.com/vllm-project/vllm-ascend.git - branch = main -[submodule "_repos/triton-ascend"] - path = _repos/triton-ascend - url = https://gitcode.com/Ascend/triton-ascend.git - branch = main -[submodule "_repos/deepspeed"] - path = _repos/deepspeed - url = https://github.com/deepspeedai/DeepSpeed.git - branch = master diff --git a/Makefile b/Makefile index 42cc2e12..addee82f 100644 --- a/Makefile +++ b/Makefile @@ -8,35 +8,17 @@ SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build -# Configure all subprojects to process -# Format: "source_directory:target_directory" -PROJECT_CONFIGS = \ - _repos/verl/docs/ascend_tutorial:sources/verl \ - _repos/VeOmni/docs:sources/VeOmni \ - _repos/LLaMA-Factory/docs:sources/LLaMA-Factory \ - _repos/ms-swift/docs:sources/ms-swift \ - _repos/vllm-ascend/docs/source:sources/vllm-ascend \ - _repos/triton-ascend/docs/zh:sources/triton-ascend \ - _repos/deepspeed/docs/_tutorials/accelerator-setup-guide.md:sources/deepspeed/quick_start.md \ - -# Configure all subprojects generated path -GENERATED_DOCS := sources/_generated - # Ascend config file path ASCEND_CONFIG := _static/ascend_config.json # Fetch script FETCH_SCRIPT := scripts/fetch_ascend_data.py -# Official ONNX Runtime CANN EP quick start source -ONNXRUNTIME_CANN_MD_URL := https://raw.githubusercontent.com/microsoft/onnxruntime/gh-pages/docs/execution-providers/community-maintained/CANN-ExecutionProvider.md -ONNXRUNTIME_CANN_MD_LOCAL := sources/_generated/sources/onnxruntime/quick_start.md - # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile copy-docs clean-submodules fetch-config sync-onnxruntime-doc init-submodules +.PHONY: help Makefile fetch-config # Fetch ascend config (always run to ensure freshness) .PHONY: $(ASCEND_CONFIG) @@ -44,80 +26,8 @@ fetch-config: @echo "Fetching ascend configuration data..." @python3 $(FETCH_SCRIPT) -# Sync latest ONNX Runtime CANN EP doc from official gh-pages branch -sync-onnxruntime-doc: - @echo "Syncing ONNX Runtime CANN quick start from upstream..." - @mkdir -p $(dir $(ONNXRUNTIME_CANN_MD_LOCAL)) - @curl -fsSL "$(ONNXRUNTIME_CANN_MD_URL)" -o "$(ONNXRUNTIME_CANN_MD_LOCAL).tmp" - @awk 'BEGIN{in_fm=0} \ - {sub(/\r$$/, "", $$0)} \ - NR==1 && $$0=="---" {in_fm=1; next} \ - in_fm && $$0=="---" {in_fm=0; next} \ - in_fm {next} \ - $$0 ~ /^##[[:space:]]+Contents[[:space:]]*$$/ {next} \ - $$0 ~ /^\{:[[:space:]]*\.no_toc[[:space:]]*\}$$/ {next} \ - $$0 ~ /^\{:[[:space:]]*toc[[:space:]]*\}$$/ {next} \ - $$0 ~ /^\*[[:space:]]*TOC[[:space:]]+placeholder[[:space:]]*$$/ {next} \ - {print}' "$(ONNXRUNTIME_CANN_MD_LOCAL).tmp" > "$(ONNXRUNTIME_CANN_MD_LOCAL)" - @rm -f "$(ONNXRUNTIME_CANN_MD_LOCAL).tmp" - @echo "Synced to $(ONNXRUNTIME_CANN_MD_LOCAL)" - -# Initialize submodules (always run to handle empty dirs left by git clone) -init-submodules: - @git submodule sync --recursive - @n=0; \ - while [ $$n -lt 3 ]; do \ - git submodule update --init --depth=1 --remote && exit 0; \ - n=$$((n+1)); \ - echo "git submodule update failed (attempt $$n/3), retrying in 8s..."; \ - sleep 8; \ - done; \ - echo "git submodule update failed after 3 attempts"; \ - exit 1 - -# Copy documentation from submodules -copy-docs: init-submodules - @echo "Preparing generated docs directory..." - @mkdir -p $(GENERATED_DOCS) - - # vllm-ascend / triton-ascend: 仅删除根 index（避免与 sources//index.rst 冲突）， - # 保留子目录 index（如 tutorials/models/index.md）供 toctree 直接引用。 - # 其他社区: 递归删除所有 index，导航由各社区 sources//index.rst 独立定义。 - @echo "Copying project documentation..." - @for config in $(PROJECT_CONFIGS); do \ - src=$$(echo $$config | cut -d: -f1); \ - rel_dst=$$(echo $$config | cut -d: -f2); \ - dst="$(GENERATED_DOCS)/$$rel_dst"; \ - echo "Copying $$src -> $$dst"; \ - rm -rf "$$dst"; \ - if [ -f "$$src" ]; then \ - mkdir -p "$$(dirname "$$dst")"; \ - echo "Copying $$src to $$dst"; \ - cp "$$src" "$$dst" || echo " [WARN] Source file missing or copy failed: $$src"; \ - elif [ -d "$$src" ]; then \ - mkdir -p "$$dst"; \ - echo "Copying $$src to $$dst"; \ - cp -r "$$src"/* "$$dst"/ 2>/dev/null || echo " [WARN] Source directory does not exist or is empty: $$src"; \ - else \ - echo " [WARN] Source does not exist: $$src"; \ - fi; \ - if [ "$$rel_dst" = "sources/vllm-ascend" ] || [ "$$rel_dst" = "sources/triton-ascend" ]; then \ - rm -f "$$dst/index.md" "$$dst/index.rst" "$$dst/index.html" 2>/dev/null || true; \ - else \ - if [ -d "$$dst" ]; then \ - find "$$dst" -name 'index.*' -delete 2>/dev/null || true; \ - fi; \ - fi; \ - done - - -# Clean up submodules -clean-submodules: - @echo "Cleaning up submodules..." - @git submodule deinit -f _repos/* - # Explicit build targets with prerequisites -html dirhtml singlehtml latex pdf: fetch-config copy-docs sync-onnxruntime-doc +html dirhtml singlehtml latex pdf: fetch-config @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # Catch-all target for other Sphinx targets (clean, help, etc.) diff --git a/README.md b/README.md index 539d62c8..61b89a77 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,15 @@ This repository is a collection of documentation for Ascend supported open sourc - `tutorial.rst`: more complex than quickstart, help people learn about **products** and solve **real world problems** by guiding them through **the entire workflow to complete a task**. See also in [Github tutorial guide](https://docs.github.com/en/contributing/style-guide-and-content-model/tutorial-content-type). - `faq.rst`: A frequently asked questions (FAQ) list. -## Documentation Available in Open Source Projects +## Documentation from Official Project Sites -- `index.rst`: the index of the opensource project doc. -- Additional source files will be automatically downloaded before running `make`. For details, see the `./Makefile`. +Some communities already maintain Ascend/NPU documentation on their own sites. Those projects are linked from the homepage cards in `index.rst` (with `target="_blank"`) instead of being built locally. Examples: verl, LLaMA-Factory, ms-swift, VeOmni, vllm-ascend, Triton-Ascend, DeepSpeed, and ONNX Runtime quick start. -Use the following command to add a subproject: +To add such a project, create a lightweight `sources//index.rst` with links to the official docs, and add it to the hidden toctree in `index.rst` so it appears in the sidebar. -```bash -git submodule add https://github.com/project.git docs/_repos/dir/ +## Local Build Prerequisites -``` +Before `make html`, the build fetches `ascend_config.json` via `scripts/fetch_ascend_data.py` (see `fetch-config` in `./Makefile`). No git submodules or document copying is involved. # Contributing diff --git a/_repos/LLaMA-Factory b/_repos/LLaMA-Factory deleted file mode 160000 index 4d8b23ac..00000000 --- a/_repos/LLaMA-Factory +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 4d8b23ace1cbb4c7ea57a9ac455b3c16ba348ed8 diff --git a/_repos/VeOmni b/_repos/VeOmni deleted file mode 160000 index 06f4d87b..00000000 --- a/_repos/VeOmni +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 06f4d87be83514d2e4f01fe20115cd693f691894 diff --git a/_repos/deepspeed b/_repos/deepspeed deleted file mode 160000 index dc0fd295..00000000 --- a/_repos/deepspeed +++ /dev/null @@ -1 +0,0 @@ -Subproject commit dc0fd2950b4cb0234ca36fa936e8d2a659b3ca04 diff --git a/_repos/ms-swift b/_repos/ms-swift deleted file mode 160000 index b59a105e..00000000 --- a/_repos/ms-swift +++ /dev/null @@ -1 +0,0 @@ -Subproject commit b59a105ec77a974b1839175c9b416f6ddc7988f9 diff --git a/_repos/triton-ascend b/_repos/triton-ascend deleted file mode 160000 index 205a6ccc..00000000 --- a/_repos/triton-ascend +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 205a6ccce339fcc704401beb3f07dc44f7e619ef diff --git a/_repos/verl b/_repos/verl deleted file mode 160000 index 7402ca73..00000000 --- a/_repos/verl +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 7402ca73bcf2b85b5337393b4ccc9ec45ea96b6d diff --git a/_repos/vllm-ascend b/_repos/vllm-ascend deleted file mode 160000 index 55c68007..00000000 --- a/_repos/vllm-ascend +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 55c680073d07ee65b6683bf5b49039141089a877 diff --git a/_static/custom.css b/_static/custom.css index 3847cc5e..cd7ec7b7 100644 --- a/_static/custom.css +++ b/_static/custom.css @@ -318,78 +318,6 @@ margin-bottom: 5%; } -body.onnxruntime-quickstart-page .rst-content { - color: #27384a; - font-size: 16px; - line-height: 1.75; -} - -body.onnxruntime-quickstart-page .rst-content h1, -body.onnxruntime-quickstart-page .rst-content h2, -body.onnxruntime-quickstart-page .rst-content h3 { - color: #1f4b8f; -} - -body.onnxruntime-quickstart-page .rst-content h1 { - border-bottom: 1px solid #d8e3f2; - padding-bottom: 8px; -} - -body.onnxruntime-quickstart-page .rst-content a { - color: #1f63d8; -} - -body.onnxruntime-quickstart-page .rst-content table.docutils { - border: 1px solid #d8e3f2; -} - -body.onnxruntime-quickstart-page .rst-content table.docutils th { - background: #f2f7ff; -} - -body.onnxruntime-quickstart-page .rst-content table.docutils tr:nth-child(even) td { - background: #f9fbff; -} - -body.onnxruntime-quickstart-page .rst-content .highlight { - background: #f7faff; - border: 1px solid #d8e3f2; - border-radius: 6px; -} - .box .flex-grow { flex-grow: 1; /* 让文本内容占据剩余空间 */ } - - -/* ========================================================= - 独立社区侧边栏专属样式 - ========================================================= */ - -#independent-sidebar .custom-sidebar-caption { - font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; - font-size: 85%; - color: #0066cc; - font-weight: 700; - text-transform: uppercase; - margin-top: 1.5em; - margin-bottom: 0.5em; - padding-left: 15px; - letter-spacing: 0.5px; -} - -#independent-sidebar ul { - margin-bottom: 0 !important; -} - -/* 覆盖菜单基础项的 padding，使其靠左贴齐 */ -#independent-sidebar ul li.toctree-l1 > a { - padding-left: 15px !important; -} - -#independent-sidebar ul li.toctree-l1.current > a { - background: #e6f0fa; /* 当前选中项高亮背景色 */ - color: #0066cc; - border-left: 4px solid #0066cc; - padding-left: 11px !important; /* 减去边框宽度保持对齐 */ -} diff --git a/_static/llamafactory_actions.js b/_static/llamafactory_actions.js deleted file mode 100644 index 472ba05e..00000000 --- a/_static/llamafactory_actions.js +++ /dev/null @@ -1,49 +0,0 @@ -$(document).ready(function () { - $.reset_selection = function (elem) { - elem.parent().children().each(function () { - $(this).removeClass("selected"); - }); - } - - $.get_options = function () { - var options = {}; - $('#col-values').children().each(function () { - var elem = $(this).find(".selected").each(function () { - var id = $(this).attr("id").split("-"); - var category = id[0]; - var value = id[1]; - options[category] = value; - }); - }); - return options; - } - - $.update_table = function () { - var options = $.get_options(); - } - - $("#col-values").on("click", ".values-element", function () { - id = $(this).attr("id"); - fields = id.split("-"); - - $.reset_selection($(this)); - $(this).addClass("selected"); - $.update_table(); - $.gen_content(); - }); - - - $.gen_content = function () { - var options = $.get_options(); - if (options['install_type'] == "docker") { - $('#install-llmf-pip-section').hide(); - $('#install-llmf-docker-section').show(); - } else if (options['install_type'] == "pip") { - $('#install-llmf-docker-section').hide(); - $('#install-llmf-pip-section').show(); - } - } - - $.update_table(); - $.gen_content(); -}); diff --git a/_static/onnxruntime_quickstart.js b/_static/onnxruntime_quickstart.js deleted file mode 100644 index 239e5892..00000000 --- a/_static/onnxruntime_quickstart.js +++ /dev/null @@ -1,14 +0,0 @@ -(function () { - function isQuickstartPage() { - var pathname = window.location.pathname.toLowerCase(); - return pathname.indexOf('onnxruntime') !== -1 && pathname.indexOf('quick_start') !== -1; - } - - document.addEventListener('DOMContentLoaded', function () { - if (!isQuickstartPage()) { - return; - } - - document.body.classList.add('onnxruntime-quickstart-page'); - }); -})(); diff --git a/_templates/layout.html b/_templates/layout.html deleted file mode 100644 index 5e3e841e..00000000 --- a/_templates/layout.html +++ /dev/null @@ -1,125 +0,0 @@ -{% extends "!layout.html" %} - -{% block menu %} -{% if is_independent %} - - - - -
- - -{% else %} - - {{ super() }} -{% endif %} -{% endblock %} \ No newline at end of file diff --git a/conf.py b/conf.py index d7045264..80f5f816 100644 --- a/conf.py +++ b/conf.py @@ -58,8 +58,6 @@ # 模板路径设置 templates_path = ['_templates'] autosummary_generate = True -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -71,9 +69,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -# _repos: submodule working trees duplicate content already copied to sources/_generated; -# indexing both roughly doubles RSS and OOM-kills low-memory cgroup builds (e.g. 2Gi). -exclude_patterns = ['_build', '_repos', 'Thumbs.db', '.DS_Store', '.venv', 'README.md'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv', 'README.md'] # -- Options for HTML output ------------------------------------------------- @@ -88,28 +84,6 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -def setup(app): - app.add_css_file('custom.css') - app.add_js_file('package_info.js') - app.add_js_file('statistics.js') - app.add_js_file('onnxruntime_quickstart.js') - - # Generate ascend_config.json if it doesn't exist (for RTD/CI builds) - import os.path - ascend_config_path = os.path.join(os.path.dirname(__file__), '_static', 'ascend_config.json') - if not os.path.exists(ascend_config_path): - print("ascend_config.json not found, generating...") - fetch_script = os.path.join(os.path.dirname(__file__), 'scripts', 'fetch_ascend_data.py') - if os.path.exists(fetch_script): - import subprocess - try: - subprocess.run(['python3', fetch_script], check=True) - except Exception as e: - print(f"Warning: Failed to generate ascend_config.json: {e}") - else: - print(f"Warning: fetch script not found at {fetch_script}") - - import os, re, importlib.util from jinja2 import Environment, FileSystemLoader @@ -198,97 +172,25 @@ def generate_api_doc(): rst_filename = os.path.join(os.getcwd(), 'sources', 'pytorch', 'api_doc.rst') with open(rst_filename, 'w', encoding='utf-8') as f: f.write(rendered_content) - -# ========================================================= -# 独立社区页面全局配置 (核心机制：高度可配置化) -# ========================================================= -html_context = { - 'independent_communities': { - 'verl': { - 'display_name': 'verl', - 'sidebar_mapping': { - 'get_start': '🚀 快速开始', - 'feature_support': '📚 特性支持', - 'dev_guide/model_dev': '🧬 模型开发', - 'dev_guide/precision_analysis': '🎯 精度调试', - 'dev_guide/performance': '⚡ 性能调优', - 'model_support/examples': '📋 最佳实践', - 'model_support': '📊 模型支持', - 'faq': '🔆 常见问题', - 'contribution_guide': '🔧 开源开发', - } - }, - 'vllm-ascend': { - 'display_name': 'vllm-ascend', - 'sidebar_mapping': { - 'getting_started': 'Getting Started', - 'user_guide': 'User Guide', - 'developer_guide': 'Developer Guide', - 'community': 'Community', - # __root_files__: 根目录下无子目录的文件需显式映射到所属分组 - # 否则侧边栏无法按目录路径自动归类 - '__root_files__': { - 'quick_start': 'getting_started', - 'installation': 'getting_started', - 'faqs': 'getting_started', - }, - } - }, - 'triton-ascend': { - 'display_name': 'Triton-Ascend', - 'sidebar_mapping': { - 'migration_guide': 'Triton 算子迁移指南', - 'examples': '典型算子样例', - 'debug_guide': '算子调试与调优', - 'triton_api': 'Triton API 接口说明', - 'triton_api_extention': '昇腾扩展 API 接口说明', - 'quick_start_group': '快速开始', - 'install_group': '安装指南', - 'arch_group': '架构设计与核心特性', - 'dev_guide_group': 'Triton 算子开发指南', - 'env_group': '环境变量', - 'faq_group': '常见问题', - '__root_files__': { - 'quick_start': 'quick_start_group', - 'installation_guide': 'install_group', - 'architecture_design_and_core_features': 'arch_group', - 'programming_guide': 'dev_guide_group', - 'environment_variable_reference': 'env_group', - 'FAQ': 'faq_group', - 'release_note': 'faq_group', - }, - } - }, - } -} - -# 【新增核心代码】：Sphinx 页面上下文注入 Hook -def update_page_context(app, pagename, templatename, context, doctree): - """ - 拦截页面渲染，判断当前路径是否属于独立社区。 - 如果是，向 Jinja 模板注入 is_independent 和对应的 comm_config 变量。 - 支持两种路径格式： - - sources/verl/... (手写页面) - - sources/_generated/sources/verl/... (从子模块拉取的页面) - """ - communities = context.get('independent_communities', {}) - context['is_independent'] = False - - for comm_id, comm_info in communities.items(): - # 匹配两种路径格式 - if pagename.startswith(f"sources/{comm_id}") or pagename.startswith(f"sources/_generated/sources/{comm_id}"): - context['is_independent'] = True - context['current_community_id'] = comm_id - context['comm_config'] = comm_info - break def setup(app): app.add_css_file('custom.css') app.add_js_file('package_info.js') app.add_js_file('statistics.js') - - # 【新增 Hook 注册】 - app.connect('html-page-context', update_page_context) + + # Generate ascend_config.json if it doesn't exist (for RTD/CI builds) + ascend_config_path = os.path.join(os.path.dirname(__file__), '_static', 'ascend_config.json') + if not os.path.exists(ascend_config_path): + print("ascend_config.json not found, generating...") + fetch_script = os.path.join(os.path.dirname(__file__), 'scripts', 'fetch_ascend_data.py') + if os.path.exists(fetch_script): + import subprocess + try: + subprocess.run(['python3', fetch_script], check=True) + except Exception as e: + print(f"Warning: Failed to generate ascend_config.json: {e}") + else: + print(f"Warning: fetch script not found at {fetch_script}") # 在 Sphinx 构建之前调用该函数生成 API 文档 try: diff --git a/index.rst b/index.rst index eeba478e..1446a785 100644 --- a/index.rst +++ b/index.rst @@ -127,12 +127,11 @@
官方链接|安装指南|快速上手
- +

DeepSpeed

DeepSpeed is a deep learning optimization library that makes distributed training and inference easy, efficient, and effective.

-
官方链接|安装指南| - 快速上手
+
官方链接|文档中心|昇腾教程
@@ -168,18 +167,18 @@

🧠 大模型/多模态训练与微调

- +

LLaMA-Factory

Unified Efficient Fine-Tuning of 100+ LLMs & VLMs。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|NPU 安装
- +

ms-swift

高效微调框架，支持 600+ LLM 和 300+ MLLM 适配昇腾。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|NPU 支持
@@ -203,18 +202,18 @@
官方链接|安装指南|快速上手
- +

VeOmni

Scaling Any Modality Model Training with Model-Centric Distributed Recipe Zoo。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|昇腾教程
- +

verl

用于 LLM 的强化学习训练库，适配昇腾并行计算方案。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|昇腾教程
@@ -243,11 +242,11 @@
官方链接|安装指南|快速上手
- +

onnxruntime

跨平台高性能推理加速器，v1.13.1 起支持昇腾。

-
官方链接|安装指南|快速上手
+
官方链接|安装指南|快速上手
@@ -271,11 +270,11 @@
官方链接|安装指南|快速上手
- +

vLLM-Ascend

面向昇腾 NPU 的 vLLM 社区插件，支持主流大模型高性能推理加速。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|快速上手
@@ -283,11 +282,11 @@

⚙️ 算子开发与编程

- +

Triton-Ascend

适配昇腾 NPU 的 Triton 语言后端，支持高性能算子开发与迁移。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|快速上手
diff --git a/sources/LLaMA-Factory/index.rst b/sources/LLaMA-Factory/index.rst index c8acdba6..4b84fde3 100644 --- a/sources/LLaMA-Factory/index.rst +++ b/sources/LLaMA-Factory/index.rst @@ -1,8 +1,8 @@ LLaMA-Factory -============== +============= -.. toctree:: - :maxdepth: 3 +NPU 相关文档由 LLaMA-Factory 官方维护，请访问官方文档站： - ../_generated/sources/LLaMA-Factory/source/multibackend/npu/npu_installation - ../_generated/sources/LLaMA-Factory/source/multibackend/npu/npu_training +- GitHub：`LLaMA-Factory `_ +- 文档中心：`LLaMA-Factory Docs `_ +- NPU 安装：`NPU Installation `_ diff --git a/sources/VeOmni/index.rst b/sources/VeOmni/index.rst index 132aa32d..724e0d9f 100644 --- a/sources/VeOmni/index.rst +++ b/sources/VeOmni/index.rst @@ -1,9 +1,8 @@ VeOmni -============ +====== -.. toctree:: - :maxdepth: 3 +昇腾相关文档由 VeOmni 官方维护，请访问官方文档站： - ../_generated/sources/VeOmni/get_started/installation/install_ascend_arm - ../_generated/sources/VeOmni/get_started/installation/install_ascend_x86 - ../_generated/sources/VeOmni/hardware_support/get_started_npu +- GitHub：`VeOmni `_ +- 文档中心：`VeOmni Docs `_ +- 昇腾教程：`Get Started on NPU `_ diff --git a/sources/deepspeed/index.rst b/sources/deepspeed/index.rst index 5f8dc2e7..2eb6eba7 100644 --- a/sources/deepspeed/index.rst +++ b/sources/deepspeed/index.rst @@ -1,7 +1,8 @@ DeepSpeed -=========== +========= -.. toctree:: - :maxdepth: 2 +昇腾相关文档由 DeepSpeed 官方维护，请访问官方文档站： - ../_generated/sources/deepspeed/quick_start +- GitHub：`DeepSpeed `_ +- 文档中心：`Accelerator Setup Guide `_ +- 昇腾教程：`Huawei Ascend NPU `_ diff --git a/sources/ms-swift/index.rst b/sources/ms-swift/index.rst index 4c41090e..55dd66dc 100644 --- a/sources/ms-swift/index.rst +++ b/sources/ms-swift/index.rst @@ -1,8 +1,8 @@ ms-swift -============ +======== -.. toctree:: - :maxdepth: 3 +NPU 相关文档由 ms-swift 官方维护，请访问官方文档站： - ../_generated/sources/ms-swift/source/BestPractices/NPU-support - ../_generated/sources/ms-swift/source_en/BestPractices/NPU-support +- GitHub：`ms-swift `_ +- 文档中心：`SWIFT Docs `_ +- NPU 支持：`NPU Support `_ diff --git a/sources/onnxruntime/index.rst b/sources/onnxruntime/index.rst index 78e0dfed..f464ef0b 100644 --- a/sources/onnxruntime/index.rst +++ b/sources/onnxruntime/index.rst @@ -5,4 +5,3 @@ onnxruntime :maxdepth: 2 install.rst - ../_generated/sources/onnxruntime/quick_start diff --git a/sources/triton-ascend/index.rst b/sources/triton-ascend/index.rst index b4490462..2e185538 100644 --- a/sources/triton-ascend/index.rst +++ b/sources/triton-ascend/index.rst @@ -1,209 +1,8 @@ Triton-Ascend -============================================ +============= -.. raw:: html +完整文档由 Triton-Ascend 官方维护，请访问官方文档站： - - -
- -
- Triton-Ascend Logo -

Triton-Ascend

-

- 适配昇腾 NPU 的 Triton 语言后端 · 高性能算子开发与迁移 -

-
- 📖 GitCode 仓库 -
-
- -

🚀 快速开始

-
- -
📦
-

安装指南

-

环境准备与安装步骤

- - -
🚀
-

快速上手

-

编写第一个 Triton 算子

- - -
📖
-

算子开发指南

-

Triton 编程模型与开发实践

- - -
🧪
-

典型算子样例

-

Softmax、Attention、MatMul 等

- -
- -
-

✨ 核心特性

-
- 🔌 昇腾 NPU 后端适配 - 🧩 丰富算子样例 - 🔧 调试与性能调优工具 - 🤝 完整 API 参考 -
-
- -
- ----- - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 快速开始 - - ../_generated/sources/triton-ascend/quick_start - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 安装指南 - - ../_generated/sources/triton-ascend/installation_guide - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 架构设计与核心特性 - - ../_generated/sources/triton-ascend/architecture_design_and_core_features - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Triton 算子开发指南 - - ../_generated/sources/triton-ascend/programming_guide - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Triton 算子迁移指南 - - ../_generated/sources/triton-ascend/migration_guide/architecture_difference - ../_generated/sources/triton-ascend/migration_guide/migrate_from_gpu - ../_generated/sources/triton-ascend/migration_guide/performance_guidelines - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 典型算子样例 - - ../_generated/sources/triton-ascend/examples/index - ../_generated/sources/triton-ascend/examples/01_vector_add_example - ../_generated/sources/triton-ascend/examples/02_fused_softmax_example - ../_generated/sources/triton-ascend/examples/03_layer_norm_example - ../_generated/sources/triton-ascend/examples/04_fused_attention_example - ../_generated/sources/triton-ascend/examples/05_matrix_multiplication_example - ../_generated/sources/triton-ascend/examples/06_autotune_example - ../_generated/sources/triton-ascend/examples/07_accuracy_comparison_example - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 算子调试与调优 - - ../_generated/sources/triton-ascend/debug_guide/debugging - ../_generated/sources/triton-ascend/debug_guide/profiling - -.. toctree:: - :maxdepth: 3 - :hidden: - :caption: Triton API 接口说明 - - ../_generated/sources/triton-ascend/triton_api/index - ../_generated/sources/triton-ascend/triton_api/triton/index - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 昇腾扩展 API 接口说明 - - ../_generated/sources/triton-ascend/triton_api_extention/index - -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: 环境变量 - - ../_generated/sources/triton-ascend/environment_variable_reference - -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: 常见问题 - - ../_generated/sources/triton-ascend/FAQ - ../_generated/sources/triton-ascend/release_note +- GitHub：`triton-ascend `_ +- 文档中心：`Triton-Ascend Docs `_ +- 快速上手：`Quick Start `_ diff --git a/sources/verl/index.rst b/sources/verl/index.rst index 92e14c1c..3cb44274 100644 --- a/sources/verl/index.rst +++ b/sources/verl/index.rst @@ -1,205 +1,8 @@ verl -============================================ +==== -.. raw:: html +昇腾相关文档由 verl 官方维护，请访问官方文档站： - - -
- -
-

🚀 verl

-

灵活、高效的大语言模型强化学习训练框架

-
- 📖 GitHub 仓库 -
-
- - -

🚀 快速开始

-
- -
📦
-

安装指南

-

昇腾 NPU 自定义环境安装

- - -
🚀
-

快速上手

-

环境搭建与基础训练示例

- - -
🔧
-

特性支持

-

昇腾后端特性与 NPU 能力说明

- - -
👨‍💻
-

开源开发

-

CI 流程与社区贡献指南

- -
- - -
-

✨ 核心特性

-
-
🧬 多样化 RL 算法
-
⚡ 业界领先吞吐量
-
🤗 HuggingFace 集成
-
🎯 昇腾 NPU 支持
-
-
-
- ----- - -.. 以下 toctree 引用 make copy-docs 生成的 _generated 内容，目录分组与 -.. sources/_generated/sources/verl/README.md 及 conf.py 中 sidebar_mapping 保持一致。 - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 🚀 快速开始 - - ../_generated/sources/verl/get_start/install_guidance - ../_generated/sources/verl/get_start/quick_start - ../_generated/sources/verl/get_start/dockerfile_build_guidance - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 📚 特性支持 - - ../_generated/sources/verl/feature_support/ascend_backend_features - ../_generated/sources/verl/feature_support/npu_advance_features - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 🧬 模型开发 - - ../_generated/sources/verl/dev_guide/model_dev/transfer_to_npu_guide - ../_generated/sources/verl/dev_guide/model_dev/parameter_and_metrics - ../_generated/sources/verl/dev_guide/model_dev/evaluation - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 🎯 精度调试 - - ../_generated/sources/verl/dev_guide/precision_analysis/precision_alignment_zh - ../_generated/sources/verl/dev_guide/precision_analysis/precision_debugger_zh - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: ⚡ 性能调优 - - ../_generated/sources/verl/dev_guide/performance/ascend_performance_analysis_guide - ../_generated/sources/verl/dev_guide/performance/perf_tuning_on_ascend - ../_generated/sources/verl/dev_guide/performance/ascend_profiling_zh - ../_generated/sources/verl/dev_guide/performance/ascend_profiling_en - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 📊 模型支持 - - ../_generated/sources/verl/model_support/model_and_algorithm_support - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 📋 最佳实践 - - ../_generated/sources/verl/model_support/examples/dapo_multi_model_optimization_practice - ../_generated/sources/verl/model_support/examples/gspo_optimization_practice - ../_generated/sources/verl/model_support/examples/ascend_retool_best_pratice - ../_generated/sources/verl/model_support/examples/ascend_sglang_best_practices - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 🔆 常见问题 - - ../_generated/sources/verl/faq/faq - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: 🔧 开源开发 - - ../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh +- GitHub：`verl `_ +- 文档中心：`verl Docs `_ +- 昇腾教程：`Ascend Tutorial `_ diff --git a/sources/vllm-ascend/index.rst b/sources/vllm-ascend/index.rst index 7eba58f2..bbbb0482 100644 --- a/sources/vllm-ascend/index.rst +++ b/sources/vllm-ascend/index.rst @@ -1,177 +1,8 @@ vLLM-Ascend -============================================ +=========== -.. raw:: html +完整文档由 vLLM-Ascend 官方维护，请访问官方文档站： - - -
- - -
-

vllm-ascend

-

- 面向昇腾 NPU 的 vLLM 社区插件 · 高性能 LLM 推理加速 -

-
- 📖 GitHub 仓库 -
-
- - -

🚀 快速开始

-
- -
📦
-

安装指南

-

环境准备与安装步骤

- - -
🚀
-

快速上手

-

5 分钟跑通推理任务

- - -
📖
-

用户指南

-

特性配置与部署方案

- - -
👨‍💻
-

开发者指南

-

贡献代码与特性开发

- -
- - -
-

✨ 核心特性

-
- 🔌 硬件插件化架构 - ⚡ 高性能推理加速 - 🧩 丰富模型支持 - 🌐 分布式推理 - 🔧 完整工具链 - 🤝 社区共建 -
-
- -
- ----- - -.. 以下 toctree 直接引用 upstream submodule 的子目录 index 文件（如 tutorials/models/index）， -.. 无需额外的 nav RST 包装文件。路径从 sources/vllm-ascend/ 出发， -.. 通过 ../_generated/sources/vllm-ascend/ 指向 make copy-docs 生成的内容。 -.. Makefile 仅删除 upstream 根目录 index（避免与本文件冲突），子目录 index 完整保留。 - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Getting Started - - ../_generated/sources/vllm-ascend/quick_start - ../_generated/sources/vllm-ascend/installation - ../_generated/sources/vllm-ascend/tutorials/models/index - ../_generated/sources/vllm-ascend/tutorials/features/index - ../_generated/sources/vllm-ascend/tutorials/hardwares/index - ../_generated/sources/vllm-ascend/faqs - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: User Guide - - ../_generated/sources/vllm-ascend/user_guide/support_matrix/index - ../_generated/sources/vllm-ascend/user_guide/configuration/index - ../_generated/sources/vllm-ascend/user_guide/feature_guide/index - ../_generated/sources/vllm-ascend/user_guide/deployment_guide/index - ../_generated/sources/vllm-ascend/user_guide/release_notes - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Developer Guide - - ../_generated/sources/vllm-ascend/developer_guide/contribution/index - ../_generated/sources/vllm-ascend/developer_guide/feature_guide/index - ../_generated/sources/vllm-ascend/developer_guide/evaluation/index - ../_generated/sources/vllm-ascend/developer_guide/performance_and_debug/index - -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: Community - - ../_generated/sources/vllm-ascend/community/governance - ../_generated/sources/vllm-ascend/community/contributors - ../_generated/sources/vllm-ascend/community/versioning_policy - ../_generated/sources/vllm-ascend/community/user_stories/index +- GitHub：`vllm-ascend `_ +- 文档中心：`vLLM Ascend Docs `_ +- 快速上手：`Quick Start `_ From 92e83c6e7981f913e432828bf6e10d1846f9d114 Mon Sep 17 00:00:00 2001 From: zheliuyu <15750543867@163.com> Date: Thu, 13 Aug 2026 14:55:25 +0800 Subject: [PATCH 2/2] fix: fix onnxruntime & ms-swift links --- index.rst | 28 ++++++++++++++++++---------- sources/ms-swift/index.rst | 2 +- sources/onnxruntime/index.rst | 9 +++++---- sources/onnxruntime/install.rst | 33 --------------------------------- 4 files changed, 24 insertions(+), 48 deletions(-) delete mode 100644 sources/onnxruntime/install.rst diff --git a/index.rst b/index.rst index 1446a785..70f33f56 100644 --- a/index.rst +++ b/index.rst @@ -93,7 +93,7 @@ } .card-desc { font-size: 0.92rem; color: var(--text-sub); line-height: 1.6; margin-bottom: 20px; flex-grow: 1; height: 3.2em; overflow: hidden; } - /* 三要素分散等距居中显示 */ + /* 三要素分散等距居中显示；整段可点，避免点到空白处无响应 */ .card-footer { border-top: 1px solid #f2f2f7; padding-top: 15px; @@ -101,11 +101,19 @@ justify-content: space-evenly; align-items: center; font-size: 0.88rem; + position: relative; + z-index: 2; } .card-footer a { + flex: 1; + text-align: center; + padding: 8px 4px; text-decoration: none; color: var(--ascend-blue); font-weight: 500; + cursor: pointer; + position: relative; + z-index: 2; } .card-footer a:hover { text-decoration: underline; } .split { display: none; } @@ -131,7 +139,7 @@

DeepSpeed

DeepSpeed is a deep learning optimization library that makes distributed training and inference easy, efficient, and effective.

-
官方链接|文档中心|昇腾教程
+
官方链接|文档中心|昇腾教程
@@ -171,14 +179,14 @@

LLaMA-Factory

Unified Efficient Fine-Tuning of 100+ LLMs & VLMs。

-
官方链接|文档中心|NPU 安装
+
官方链接|文档中心|NPU 安装

ms-swift

高效微调框架，支持 600+ LLM 和 300+ MLLM 适配昇腾。

-
官方链接|文档中心|NPU 支持
+
官方链接|文档中心|NPU 支持
@@ -206,14 +214,14 @@

VeOmni

Scaling Any Modality Model Training with Model-Centric Distributed Recipe Zoo。

-
官方链接|文档中心|昇腾教程
+
官方链接|文档中心|昇腾教程

verl

用于 LLM 的强化学习训练库，适配昇腾并行计算方案。

-
官方链接|文档中心|昇腾教程
+
官方链接|文档中心|昇腾教程
@@ -242,11 +250,11 @@
官方链接|安装指南|快速上手
- +

onnxruntime

跨平台高性能推理加速器，v1.13.1 起支持昇腾。

-
官方链接|安装指南|快速上手
+
官方链接|文档中心|昇腾教程
@@ -274,7 +282,7 @@

vLLM-Ascend

面向昇腾 NPU 的 vLLM 社区插件，支持主流大模型高性能推理加速。

-
官方链接|文档中心|快速上手
+
官方链接|文档中心|快速上手
@@ -286,7 +294,7 @@

Triton-Ascend

适配昇腾 NPU 的 Triton 语言后端，支持高性能算子开发与迁移。

-
官方链接|文档中心|快速上手
+
官方链接|文档中心|快速上手
diff --git a/sources/ms-swift/index.rst b/sources/ms-swift/index.rst index 55dd66dc..51dd9250 100644 --- a/sources/ms-swift/index.rst +++ b/sources/ms-swift/index.rst @@ -5,4 +5,4 @@ NPU 相关文档由 ms-swift 官方维护，请访问官方文档站： - GitHub：`ms-swift `_ - 文档中心：`SWIFT Docs `_ -- NPU 支持：`NPU Support `_ +- NPU 支持：`NPU Support `_ diff --git a/sources/onnxruntime/index.rst b/sources/onnxruntime/index.rst index f464ef0b..f7172c25 100644 --- a/sources/onnxruntime/index.rst +++ b/sources/onnxruntime/index.rst @@ -1,7 +1,8 @@ onnxruntime -============ +=========== -.. toctree:: - :maxdepth: 2 +昇腾相关文档由 ONNX Runtime 官方维护，请访问官方文档站： - install.rst +- GitHub：`onnxruntime `_ +- 文档中心：`ONNX Runtime Docs `_ +- 昇腾教程：`CANN Execution Provider `_ diff --git a/sources/onnxruntime/install.rst b/sources/onnxruntime/install.rst deleted file mode 100644 index 8837bdac..00000000 --- a/sources/onnxruntime/install.rst +++ /dev/null @@ -1,33 +0,0 @@ -安装指南 -=========== - -本教程面向使用 ONNX Runtime & Ascend NPU 的开发者，帮助完成昇腾环境下 ONNX Runtime 的安装。 - -.. note:: - - 阅读本篇前，请确保已按照 :doc:`安装教程 <../ascend/quick_install>` 准备好昇腾环境！ - -ONNX Runtime 安装 -------------------- - -ONNX Runtime 目前提供了 源码编译 和 二进制包 两种安装方式，其中二进制包当前只支持Python。 - -从源码安装 -^^^^^^^^^^^^ - -.. code-block:: shell - :linenos: - - # Default path, change it if needed. - source /usr/local/Ascend/ascend-toolkit/set_env.sh - - ./build.sh --config --build_shared_lib --parallel --use_cann - - -从pip安装 -^^^^^^^^^^^^ - -.. code-block:: shell - :linenos: - - pip3 install onnxruntime-cann