Update ascend quick install documentation with dynamic configuration by hipudding · Pull Request #107 · Ascend/docs

hipudding · 2026-02-25T12:57:27Z

Dynamic ascend version configuration and build fixes
Changes

Dynamic config: Fetch ascend version data from hiascend API during build
Multithreading: Optimize data fetching with worker pool (CPU core count)
macOS build fix: Restrict torch_npu to Linux platform only
Makefile optimization: Use target dependencies to skip redundant operations

ascend-robot · 2026-02-25T12:57:36Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

ascend-robot · 2026-02-28T01:39:55Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

ascend-robot · 2026-02-28T02:16:16Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

zheliuyu · 2026-03-04T07:14:52Z

scripts/fetch_ascend_data.py

+            cpu_arch_id = task['cpu_arch_id']
+            os_id = task['os_id']
+            install_methods = get_install_methods(version_id, hardware_id, cpu_arch_id, os_id)
+            print(f"        [{threading.current_thread().name}] Found {len(install_methods)} install methods for {os_id}")


The meaning of this log message seems a bit unclear. I think we should either clarify what's happening here or just remove it — either is fine.

It has been changed to a count to avoid a large number of logs.

zheliuyu · 2026-03-04T07:40:29Z

Makefile

 	@git submodule update --init --remote

+# Copy documentation from submodules
+copy-docs: _repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift


Please rebase this part of the code so we can verify the documentation builds successfully during review.

Additionally, should we also provide a jump link for "More Versions" so that users can access other CANN versions?

ascend-robot · 2026-03-10T06:42:18Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

- Add fetch_ascend_data.py script to fetch latest data from hiascend.com - Add ascend_config.json with version, product series, CPU architectures, OS, and install methods - Refactor ascend_actions.js to load from config and dynamically generate UI - Update quick_install.rst to use dynamic selection - Update Makefile to fetch ascend data on each build - Fix conf.py to handle missing torch_npu gracefully The dynamic selection now supports: - Version selection (8.5.0, 8.5.0.alpha002) - Product series selection - CPU architecture selection - Operating system selection - Install method selection - Dynamic display of installation steps and commands

- Use CPU core count for worker threads instead of fixed 10 - Replace absolute output path with relative path - Implement task queue pattern for parallel API requests - Delete runtime-generated ascend_config.json from repo

- Fix shell syntax error in Makefile (removed stray 2. and .) - Restrict torch_npu to Linux platform only (not available on macOS) - Use venv for building

- Use directory targets for submodules to skip if already exists - Make copy-docs depend on submodule directories - Remove clean-submodules call to avoid re-initializing - Use Make's built-in target mechanism instead of shell checks

- Add "更多版本" button linking to official download page - Add footer with CANN documentation links - Simplify fetch_ascend_data.py logging output - Use dynamic version (git hash) and timestamp in config Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ascend-robot · 2026-03-10T06:45:50Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

Copilot

Pull request overview

This PR refactors the Ascend “quick install” documentation to render installation steps dynamically from a generated configuration file, and adjusts the docs build pipeline to support that generation while also improving build portability.

Changes:

Replaces the static Ascend quick-install content with a JS-driven selector UI backed by a generated _static/ascend_config.json.
Adds a Python fetch script to build the Ascend configuration from the hiascend API (with multithreaded fetching).
Improves build robustness/portability (Linux-only torch_npu, Makefile dependency wiring, and conf.py ImportError handling for API doc generation).

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
`sources/ascend/quick_install.rst`	Replaces static instructions with a dynamic UI container driven by JS/config.
`scripts/fetch_ascend_data.py`	New build-time script to fetch and serialize Ascend version/install-step data from hiascend.
`requirements.txt`	Restricts `torch_npu` installation to Linux to avoid macOS build failures.
`conf.py`	Wraps API doc generation to avoid hard failures when `torch_npu` isn’t importable.
`_static/custom.css`	Adds styling for the “更多版本” link/button and related layout tweaks.
`_static/ascend_actions.js`	Replaces static option logic with config-driven selectors and step rendering.
`Makefile`	Adds config generation + doc-copy prerequisites and introduces submodule-related targets.
`.gitignore`	Updates ignored generated paths (but currently mismatches the new config output path).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T06:56:03Z

scripts/fetch_ascend_data.py

+def main():
+    # 版本列表（手动记录）
+    versions = [
+        {'id': '673', 'name': '9.0.0-beta.1'},
+        {'id': '657', 'name': '8.5.0'},
+        {'id': '630', 'name': '8.5.0.alpha002'}
+    ]


The PR description says versions are fetched dynamically from the API, but the version list here is still manually maintained. If the API has an endpoint for available versions, consider populating versions from it; otherwise, please update the PR description (or the comment) to reflect that only the per-version detail is dynamic.

There's no api for versions.

Copilot · 2026-03-10T06:56:03Z

sources/ascend/quick_install.rst

 跟随指导，在您的机器上快速安装昇腾环境。

-1. 系统要求
----------------
-1.1 前置检查
-^^^^^^^^^^^^^
-确认昇腾AI处理器已经安装妥当
-
-.. code-block:: bash
-
-    lspci | grep 'Processing accelerators'
-
-确认操作系统架构及版本
-
-.. code-block:: bash
-
-    uname -m && cat /etc/*release
-
-确认Python版本
-
-.. code-block:: bash
-
-    python --version
-
-
-1.2 软件要求
-^^^^^^^^^^^^^
-======== ========================================
-软件     版本
-======== ========================================
-操作系统  openEuler20.03/22.03, Ubuntu 20.04/22.04
-Python   3.7, 3.8, 3.9, 3.10, 3.11.4
-======== ========================================
-
-
-2. 环境安装
------------------
-根据您的需求，选择合适的软件包版本：
-
-.. warning:: 
-
-    以下文档需要使用非root用户进行安装安装
-
 .. raw:: html

    <script type="text/javascript" src="../../_static/ascend_actions.js"></script>
    <div id="div-installation" style="">
        <div class="row">


This page now relies entirely on JS + ascend_config.json to show any installation steps. If JS is disabled, the config is missing, or the network call fails, users will effectively get an empty guide. Consider adding a non-JS fallback (e.g., a prominent link to the official install docs and/or a noscript message) so the page remains usable when dynamic loading isn’t available.

Copilot · 2026-03-10T06:56:03Z

_static/ascend_actions.js

+        if (!steps || steps.length === 0) {
+            $('#install-instructions').html('<p style="color: red;">暂无安装步骤</p>');
+            return;
        }


When there are no steps, the code writes an error message then returns, but does not .show() the #install-instructions container (which starts hidden). The user will still see nothing. Show the container (and/or ensure it’s visible when displaying errors).

Copilot · 2026-03-10T06:56:04Z

scripts/fetch_ascend_data.py

+def api_call(url):
+    """调用hiascend API"""
+    cmd = [
+        'curl', '-s',
+        '-H', 'referer: https://www.hiascend.com/cann/download',
+        '-H', 'accept: */*',
+        '-H', 'accept-language: zh-CN,zh;q=0.9',
+        '-H', 'user-agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Mobile Safari/537.36',
+        url
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        return json.loads(result.stdout)
+    return None


api_call() can hang indefinitely (no timeout) and will raise JSONDecodeError if the response isn’t valid JSON (e.g., transient HTML/captcha page), failing the build. Add a curl timeout (--max-time / --connect-timeout) or switch to a Python HTTP client with timeouts, and catch JSON parsing errors to return a controlled failure.

Copilot · 2026-03-10T06:56:04Z

Makefile

+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile $(ASCEND_CONFIG) copy-docs
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)


The catch-all % target now depends on $(ASCEND_CONFIG) and copy-docs, so make clean (and any other sphinx-build -M targets) will fetch API data and copy submodule docs before running the requested target. Consider adding explicit build targets (html/dirhtml/etc.) with these prerequisites and keeping clean free of them.

Copilot · 2026-03-10T06:56:05Z

Makefile

+_repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift:
 	@echo "Initializing submodules..."
 	@git submodule update --init --remote


git submodule update --init --remote makes builds non-reproducible because it updates submodules to the latest remote tracking commits rather than the commits pinned in this repo. If reproducible doc builds are important (especially in CI/RTD), consider removing --remote and relying on the checked-in submodule SHAs (or explicitly documenting why tracking remote heads is required).

Copilot · 2026-03-10T06:56:05Z

_static/ascend_actions.js

+    function loadConfig() {
+        $.getJSON('../../_static/ascend_config.json', function(data) {
+            config = data;
+            initializeUI();
+        }).fail(function() {
+            console.error('Failed to load ascend_config.json');
+            $('#install-instructions').html('<p style="color: red;">加载配置文件失败，请检查网络连接。</p>');
        });


The config-load failure path updates #install-instructions, but that element is initially display:none in the RST, so the error message won’t be visible. Consider calling .show() (or writing into a visible container) in the .fail() handler so users aren’t left with an empty page when ascend_config.json is missing/unreachable.

Copilot · 2026-03-10T06:56:05Z

_static/ascend_actions.js

+        var versionHtml = '<div class="mobile-headings">版本</div>';
+        versionKeys.forEach(function(key, index) {
+            var version = versions[key];
+            var selected = index === 0 ? 'selected' : '';
+            versionHtml += '<div class="values-element block-' + versionKeys.length + ' install-version ' + selected + '" id="version-' + key + '">' + version.name + '</div>';
        });
-        return os_versions;
-    }
+        $('#row-version').html(versionHtml);


Option labels from ascend_config.json (e.g., version.name) are inserted into HTML without escaping. If the config ever contains unexpected characters/markup, this becomes an XSS vector in the rendered docs. Please HTML-escape all user/API-provided strings (version/product/os/install method names) or set text via DOM APIs instead of string concatenation.

Copilot · 2026-03-10T06:56:06Z

_static/ascend_actions.js

+        var instructionsHtml = '';
+        steps.forEach(function(step, index) {
+            instructionsHtml += '<section>';
+            instructionsHtml += '<h3>' + (index + 1) + '. ' + step.title + '</h3>';
+


step.title is inserted into the <h3> without escaping. Even if commands are escaped, an unescaped title can still inject markup/scripts if the upstream HTML contains unexpected content. Reuse escapeHtml() (or DOM text nodes) for titles as well.

Copilot · 2026-03-10T06:56:06Z

_static/ascend_actions.js

+        // 添加底部提示信息
+        instructionsHtml += '<section class="install-footer">';
+        instructionsHtml += '<p>若您需要详细的操作步骤请参考';
+        instructionsHtml += '<a href="https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850/quickstart/instg_quick.html" target="_blank">《CANN快速开始》</a>';
+        instructionsHtml += '或';
+        instructionsHtml += '<a href="https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850/softwareinst/instg/instg_0000.html?Mode=PmIns&InstallType=netconda&OS=openEuler" target="_blank">《CANN安装指南》</a>。';
+        instructionsHtml += '</p>';


The footer links are hard-coded to CANNCommunityEdition/850, which may not match the selected version (e.g., 9.0.0-beta.1 in the config). If possible, derive these URLs from the selected version or make the link text clearly indicate it’s a fixed reference version to avoid sending users to incompatible docs.

- Add timeout and JSON error handling to API calls - Use try/finally in worker to prevent deadlock on exceptions - Cap worker threads to avoid API throttling - Escape HTML in all UI strings to prevent XSS - Clamp block CSS class to max 5 for layout stability - Show error container when config load fails or no steps - Add noscript fallback for JS-disabled browsers - Remove --remote from submodule update for reproducible builds - Separate build targets so clean doesn't trigger data fetch - Auto-generate ascend_config.json in conf.py for RTD/CI builds Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ascend-robot · 2026-03-10T07:29:58Z

CLA Signature Pass

hipudding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

ascend-robot added the ascend-cla/yes label Feb 25, 2026

hipudding marked this pull request as ready for review February 28, 2026 02:19

hipudding requested review from fffrog and zheliuyu and removed request for zheliuyu February 28, 2026 02:19

zheliuyu reviewed Mar 4, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 10, 2026 06:42

Copilot started reviewing on behalf of hipudding March 10, 2026 06:42 View session

hipudding and others added 8 commits March 10, 2026 14:44

Optimize fetch_ascend_data.py with multithreading

698a801

- Use CPU core count for worker threads instead of fixed 10 - Replace absolute output path with relative path - Implement task queue pattern for parallel API requests - Delete runtime-generated ascend_config.json from repo

Fix build issues

37b221e

- Fix shell syntax error in Makefile (removed stray 2. and .) - Restrict torch_npu to Linux platform only (not available on macOS) - Use venv for building

Add ascend_config.json to gitignore

df95a98

Add sources/_generated/ to gitignore

ded0cfe

Optimize Makefile with proper target dependencies

1115b42

- Use directory targets for submodules to skip if already exists - Make copy-docs depend on submodule directories - Remove clean-submodules call to avoid re-initializing - Use Make's built-in target mechanism instead of shell checks

Add .tasks, venv, _repos to gitignore

2ded914

hipudding force-pushed the main branch from 34ef995 to a5d2d45 Compare March 10, 2026 06:45

hipudding requested a review from zheliuyu March 10, 2026 06:50

Copilot AI reviewed Mar 10, 2026

View reviewed changes

hipudding merged commit a33e771 into Ascend:main Mar 10, 2026
1 check failed

Conversation

hipudding commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ascend-robot commented Feb 25, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Feb 28, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Feb 28, 2026

CLA Signature Pass

Uh oh!

zheliuyu Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

hipudding Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

hipudding Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

zheliuyu Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

zheliuyu Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

hipudding Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

hipudding Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

Uh oh!

Reviewers

hipudding commented Feb 25, 2026 •

edited

Loading