feat: Implement configurable independent community sub-sites with modular navigation base on verl by justbin-coder · Pull Request #111 · Ascend/docs

justbin-coder · 2026-03-09T17:32:18Z

verview
This PR introduces a generic, highly extensible solution for "independent community sub-sites". Using the verl community as the first use case, it achieves sidebar content isolation, modular navigation based on the developer journey, and dynamic extraction of in-page TOCs for long documents. Future communities can be onboarded seamlessly by simply updating a configuration dict without any code changes.

Core Modifications

conf.py: Added the independent_communities dictionary and an update_page_context hook to intercept paths during build and dynamically inject community configs to the frontend.
_templates/layout.html: Utilized JS to dynamically reconstruct the DOM. It extracts the current community's directory tree, generates native-compliant category captions, and smartly elevates deep TOC levels to display inner headings.
_static/custom.css: Added dedicated styles for #independent-sidebar, perfectly inheriting the active highlights and collapsible interactions of the native Sphinx RTD theme.
Doc Source Files: Optimized the inclusion method for long documents (using MyST include) to resolve duplicate H1 conflicts and blank rendering issues.

Testing & Effects

Navigation Isolation: Navigating to the verl community exclusively displays its own documents in the left sidebar, successfully hiding global unrelated content.
Modular Categorization: The sidebar correctly categorizes items into modules like "Getting Started", "Application Guide", etc.
Long Document Experience: When opening long Markdown documents (e.g., Ascend Performance Analysis Guide), its inner H2/H3 headings correctly expand and track active highlights in the left sidebar, with the main content rendering completely on the right.

ascend-robot · 2026-03-09T17:32:28Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T08:11:21Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T08:14:41Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T09:38:23Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:18:57Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:24:22Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:41:13Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:42:12Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:43:37Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:56:57Z

CLA Signature Pass

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

ascend-robot · 2026-03-10T11:59:13Z

CLA Signature Pass

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

justbin-coder · 2026-03-10T11:59:31Z

tardis-key · 2026-03-10T12:11:59Z

What's in _static/ascend_config.json, such a huge change

zheliuyu

Thanks very much for bringing usability features to the Ascend/docs. Here are a few review comments for your reference.

In general, we prefer to maintain the original architecture of automated documentation builds without adding excessive local documentation. Ideally, the ./sources folder should only contain directory indexes for the documentation, which would significantly reduce maintenance overhead.

zheliuyu · 2026-03-11T01:09:02Z

sources/verl/core_features_application_guide/ascend_retool_best_pratice.rst

@@ -0,0 +1,2 @@
+


These documentation files only contain include directives. Could this functionality be automated during the make stage—for example, by moving it into the Makefile?

The documentation is now configured to reference the official upstream files directly

zheliuyu · 2026-03-11T01:09:44Z

sources/verl/open_source_development/ascend_ci_guide_zh.rst

@@ -0,0 +1,2 @@
+


zheliuyu · 2026-03-11T01:11:54Z

conf.py

 # ones.
 extensions = [
-    'recommonmark',
+    # 'recommonmark',


If it is confirmed that recommonmark is no longer needed, it can be removed directly.

zheliuyu · 2026-03-11T01:15:39Z

conf.py

+                'open_source_development': '🔧 开源开发'
+            }
+        },
+        # 未来增加 sglang，只需在这里解除注释即可，不用改代码


Following clean code practices, any temporarily unavailable feature should be deleted, not just commented out.

zheliuyu · 2026-03-11T01:22:39Z

_static/ascend_config.json

It seems that ascend_config.json turns an automated documentation build into a local one. This approach introduces excessive code and is difficult to maintain. I recommend sticking with the original method.

ascend-robot · 2026-03-17T06:58:11Z

CLA Signature Pass

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

ascend-robot · 2026-03-17T07:58:51Z

CLA Signature Pass

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

ascend-robot · 2026-03-17T08:20:45Z

CLA Signature Pass

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

justbin-coder · 2026-03-17T08:26:40Z

justbin-coder · 2026-03-17T08:31:51Z

What's in _static/ascend_config.json, such a huge change

this large change in _static/ascend_config.json was triggered automatically after updating the Makefile. I have removed the file from the current commit and added it to .gitignore to keep the PR clean. i think it must to refactor the configuration writing logic in a future PR to prevent this issue.

zheliuyu · 2026-03-19T03:24:52Z

sources/verl/index.rst

+      <!-- 快速开始 -->
+      <h2 class="verl-section-title">🚀 快速开始</h2>
+      <div class="verl-quick-grid">
+         <a href="../_generated/sources/verl/quick_start/ascend_quick_start.html" class="verl-quick-card">


It seems that there is an error in the referenced documentation path.

zheliuyu · 2026-03-19T03:29:02Z

sources/verl/index.rst

@@ -1,12 +1,247 @@
-verl
-============
+verl - 大模型强化学习训练框架


建议去掉标题中的 ”大模型强化学习训练框架“ ，以便和目录中其他项目的名称保持一致。对项目所在应用领域的注解可在文档正文中给出。

…avigation base on verl

ascend-robot · 2026-03-19T07:57:28Z

CLA Signature Pass

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

justbin-coder · 2026-03-19T07:58:37Z

…skip issue

ascend-robot · 2026-03-20T07:26:27Z

CLA Signature Pass

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

ascend-robot added the ascend-cla/yes label Mar 9, 2026

justbin-coder force-pushed the verl-portal branch from 389eddf to 86defb6 Compare March 10, 2026 08:14

justbin-coder force-pushed the verl-portal branch from 86defb6 to 2bd7f4a Compare March 10, 2026 09:38

justbin-coder force-pushed the verl-portal branch from 2bd7f4a to 2b1830a Compare March 10, 2026 11:18

justbin-coder force-pushed the verl-portal branch from 9cd7dbc to c0e794d Compare March 10, 2026 11:41

justbin-coder force-pushed the verl-portal branch from c0e794d to f786fde Compare March 10, 2026 11:42

justbin-coder force-pushed the verl-portal branch from 4b63b32 to 5a2e814 Compare March 10, 2026 11:56

justbin-coder force-pushed the verl-portal branch from 5a2e814 to 48c102e Compare March 10, 2026 11:59

zheliuyu reviewed Mar 11, 2026

View reviewed changes

justbin-coder force-pushed the verl-portal branch from 48c102e to ff7a1ae Compare March 17, 2026 06:58

justbin-coder force-pushed the verl-portal branch from 1e02772 to 4edd786 Compare March 17, 2026 08:20

zheliuyu reviewed Mar 19, 2026

View reviewed changes

justbin-coder added 2 commits March 19, 2026 06:52

Implement configurable independent community sub-sites with modular n…

bfe5acb

…avigation base on verl

refactor(verl): simplify landing page

f88b189

justbin-coder force-pushed the verl-portal branch from 4edd786 to f88b189 Compare March 19, 2026 07:57

fix(makefile): use .PHONY target for submodule init to fix empty dir …

0e2a0ca

…skip issue

zheliuyu merged commit 1fdc48d into Ascend:main Mar 23, 2026
1 check passed

Conversation

justbin-coder commented Mar 9, 2026

Uh oh!

ascend-robot commented Mar 9, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 10, 2026

CLA Signature Pass

Uh oh!

justbin-coder commented Mar 10, 2026

Uh oh!

tardis-key commented Mar 10, 2026

Uh oh!

zheliuyu left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ascend-robot commented Mar 17, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 17, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Mar 17, 2026

CLA Signature Pass

Uh oh!

justbin-coder commented Mar 17, 2026

Uh oh!

justbin-coder commented Mar 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ascend-robot commented Mar 19, 2026

CLA Signature Pass

Uh oh!

zheliuyu left a comment •

edited

Loading