From 18b211c7ecb04c30c2bac5d5c3c4ae83ad9f8a12 Mon Sep 17 00:00:00 2001 From: Kiss Date: Tue, 19 May 2026 12:09:55 +0200 Subject: [PATCH 1/6] Add markdown button and make llms.txt available --- docs/conf.py | 135 +++++++++++++++++++++++++++++++++++++++++++++++--- docs/llms.txt | 19 +++++++ 2 files changed, 146 insertions(+), 8 deletions(-) create mode 100644 docs/llms.txt diff --git a/docs/conf.py b/docs/conf.py index fa908a2..49b74ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,10 +1,13 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html +"""Configuration file for the Sphinx documentation builder.""" +import os +import re +from pathlib import Path + +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "instinct.docs.amd.com") +html_context = {} +if os.environ.get("READTHEDOCS", "") == "True": + html_context["READTHEDOCS"] = True -# configurations for PDF output by Read the Docs project = "AMD Instinct Hub" html_title = "GPU cluster networking documentation" author = "Advanced Micro Devices, Inc." @@ -19,11 +22,127 @@ html_theme = "rocm_docs_theme" html_theme_options = { - "flavor": "instinct" + "flavor": "instinct", + "link_main_doc": True, + "use_download_button": True, } extensions = ["rocm_docs"] html_static_path = ['_static'] +EXCLUDED_DIRS = { + "_build", + "_templates", + "_static", + ".git", + ".venv", +} + +MARKUP_PREFIXES = ( + ":::", + "```{", + "```", + ":img-top:", + ":class", + ":link:", + ":link-type:", + ":shadow:", + ":columns:", + ":padding:", + ":gutter:", + ":open:", + ":name:", + ":header-rows:", + ":alt:", + "+++", + "<", + "-->", + "{bdg-", +) + +# Matches lines like "align: center", "alt:", "name: foo" (directive options +# not starting with a colon, common in MyST figure/table fences) +_BARE_DIRECTIVE_RE = re.compile(r"^[a-z][a-z_-]*:\s*\S*$") + +# Matches MyST/RST anchor labels like "(some-label)=" +_ANCHOR_LABEL_RE = re.compile(r"^\(\w[\w-]*\)=$") + +MIN_PROSE_LINES = 10 + + +def should_skip(path: Path) -> bool: + return any(part in EXCLUDED_DIRS for part in path.parts) + + +def is_prose_line(line: str) -> bool: + stripped = line.strip() + if not stripped: + return False + if stripped.startswith(MARKUP_PREFIXES): + return False + # Drop bare directive-option lines (e.g. "align: center", "alt:") + if _BARE_DIRECTIVE_RE.match(stripped): + return False + # Drop MyST/RST anchor labels (e.g. "(some-label)=") + if _ANCHOR_LABEL_RE.match(stripped): + return False + # Drop lines that contain an HTML tag anywhere (e.g. ".

") + if re.search(r" Configure and validate high-performance network infrastructure for AMD Instinct GPU clusters. Covers single-node NIC and PCIe validation, multi-node RDMA/RoCE configuration, ROCm-aware MPI with UCX and libfabric, RCCL collective benchmarking, and multi-node LLM inference load balancing. + +## How to + +- [GPU-enabled MPI](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/gpu-enabled-mpi.html): Configure ROCm-aware Open MPI with UCX for InfiniBand and RoCE, set up libfabric for Slingshot, enable UCC for GPU-aware collective operations, and run OSU Micro Benchmarks to validate MPI bandwidth and latency. +- [Single-node network configuration](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/single-node-config.html): Validate PCIe link speed and width for GPU-to-NIC connectivity, tune Mellanox and Broadcom NIC settings, run RVS PCIe tests, and benchmark GPU memory bandwidth with TransferBench and ROCm Bandwidth Test. +- [Multi-node network configuration](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/multi-node-config.html): Run OFED perftest benchmarks for host-to-host and device-to-device RDMA, validate multi-threaded throughput, configure RCCL environment variables for multi-node collective operations, and benchmark with OSU Micro Benchmarks. +- [Multi-node inference with load balancing](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/multi-node-inference-lb.html): Deploy multi-node LLM inference clusters using vLLM or SGLang, configure LiteLLM or Nginx as load-balancing gateways, set up Prometheus and Grafana for monitoring, and run load tests with k6 or Apache Bench. +- [RoCE network configuration](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/roce-network-config.html): Configure RoCE NICs and switches for GPU cluster networks, prevent ARP flux and routing isolation issues, and apply recommended NIC and switch settings for RDMA over Converged Ethernet. +- [Troubleshooting](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/how-to/troubleshooting.html): Diagnose RCCL and RDMA errors using error reference tables, resolve network connectivity, firewall, ACS, NUMA balancing, and LD_LIBRARY_PATH issues, and fix MPI interface exclusion and BIOS misconfiguration problems. + +## Reference + +- [Hardware support](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/reference/hardware-support.html): GPU architecture ROCm version requirements (MI355X/MI350X require ROCm 7.0.1+, MI325X requires 6.3.1+) and NIC compatibility matrices per AMD Instinct GPU generation. +- [Cluster design](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/reference/cluster-design.html): Reference cluster network design guides and topology PDFs for AMD Instinct GPU deployments ranging from 128 to 8192 GPUs using leaf-spine architectures. + +--- From 3fbadfd89ecd803cec0ee59f41f1c6b07e9f8f41 Mon Sep 17 00:00:00 2001 From: Kiss Date: Thu, 21 May 2026 12:17:15 +0200 Subject: [PATCH 2/6] Add llms-full.txt and keep the llms.txt as base --- docs/conf.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 49b74ee..4399a3b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,8 @@ html_static_path = ['_static'] +html_extra_path = ["llms.txt"] + EXCLUDED_DIRS = { "_build", "_templates", @@ -67,6 +69,9 @@ # Matches MyST/RST anchor labels like "(some-label)=" _ANCHOR_LABEL_RE = re.compile(r"^\(\w[\w-]*\)=$") +# Matches RST section underlines (e.g. "====", "----", "~~~~") +_RST_UNDERLINE_RE = re.compile(r"^[=\-~^\"\'#*+]{3,}$") + MIN_PROSE_LINES = 10 @@ -89,6 +94,15 @@ def is_prose_line(line: str) -> bool: # Drop lines that contain an HTML tag anywhere (e.g. ".

") if re.search(r" Date: Fri, 29 May 2026 11:58:55 +0200 Subject: [PATCH 3/6] Update the filter function of llms-full.txt generation --- docs/conf.py | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4399a3b..bd25bb4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -72,6 +72,9 @@ # Matches RST section underlines (e.g. "====", "----", "~~~~") _RST_UNDERLINE_RE = re.compile(r"^[=\-~^\"\'#*+]{3,}$") +# Matches RST code block directives (e.g. ".. code-block:: cpp", ".. code:: sh") +_RST_CODE_BLOCK_RE = re.compile(r"^\.\.\s+(code-block|code|sourcecode)::") + MIN_PROSE_LINES = 10 @@ -91,14 +94,13 @@ def is_prose_line(line: str) -> bool: # Drop MyST/RST anchor labels (e.g. "(some-label)=") if _ANCHOR_LABEL_RE.match(stripped): return False - # Drop lines that contain an HTML tag anywhere (e.g. ".

") - if re.search(r"` describes..."). + if re.match(r"^:[A-Za-z][A-Za-z0-9_-]*:(\s|$)", stripped): return False # Drop RST section underlines (e.g. "====", "----", "~~~~") if _RST_UNDERLINE_RE.match(stripped): @@ -145,10 +147,32 @@ def generate_combined_markdown(app, exception): continue relative = doc_file.relative_to(docs_root) - cleaned = "\n".join( - line for line in lines - if line.strip() == "" or is_prose_line(line) - ) + in_backtick_fence = False + in_rst_code_block = False + kept = [] + for line in lines: + stripped = line.strip() + # Backtick fences (MyST/Markdown) + if stripped.startswith("```"): + in_backtick_fence = not in_backtick_fence + kept.append(line) + continue + if in_backtick_fence: + kept.append(line) + continue + # RST code block: exit when a non-blank, non-indented line appears + if in_rst_code_block: + if not stripped or line[0] in (" ", "\t"): + kept.append(line) + continue + in_rst_code_block = False + # RST code block: enter on directive line (directive itself is dropped) + if _RST_CODE_BLOCK_RE.match(stripped): + in_rst_code_block = True + continue + if not stripped or is_prose_line(line): + kept.append(line) + cleaned = "\n".join(kept) combined.append(f"\n\n---\n\n# {relative}\n") combined.append(cleaned.strip()) From 008e9eab2cf09443725cc2f9bbc1ef7dd4d81b04 Mon Sep 17 00:00:00 2001 From: Kiss Date: Fri, 29 May 2026 13:06:00 +0200 Subject: [PATCH 4/6] sync llms filter fixes from rocm-docs-core --- docs/conf.py | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index bd25bb4..6f15cf7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,7 +57,6 @@ ":header-rows:", ":alt:", "+++", - "<", "-->", "{bdg-", ) @@ -75,6 +74,17 @@ # Matches RST code block directives (e.g. ".. code-block:: cpp", ".. code:: sh") _RST_CODE_BLOCK_RE = re.compile(r"^\.\.\s+(code-block|code|sourcecode)::") +# Matches markdown table separator rows (e.g. "|---|---|", "| :--- | ---: |"). +_MD_TABLE_SEP_RE = re.compile(r"^\|[\s|:\-]+\|$") + +# Matches RST directives whose indented body should be discarded (e.g. raw HTML). +_RST_SKIP_BLOCK_RE = re.compile(r"^\.\.\s+raw::") + +# Matches HTML tags (e.g. "
", "

", ") - Add in_html_open_tag state to discard multi-line HTML opening tag continuations --- docs/conf.py | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 6f15cf7..7b0bf18 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,6 +85,10 @@ # URL schemes so that multi-line RST inline hyperlinks are preserved. _HTML_TAG_RE = re.compile(r"^<(?!https?://|ftp://|mailto:)[a-zA-Z/!]") +# Matches trailing HTML close tags at the end of a prose line +# (e.g. "Browse blogs.

", "See the guide."). +_TRAILING_HTML_CLOSE_RE = re.compile(r"()+\s*$") + MIN_PROSE_LINES = 10 @@ -171,6 +175,8 @@ def generate_combined_markdown(app, exception): in_backtick_fence = False in_rst_code_block = False in_rst_skip_block = False + in_html_comment = False # inside block + in_html_open_tag = False # inside a multi-line HTML opening tag kept = [] for line in lines: stripped = line.strip() @@ -182,6 +188,11 @@ def generate_combined_markdown(app, exception): if in_backtick_fence: kept.append(line) continue + # HTML comment block (): discard all content until --> + if in_html_comment: + if "-->" in stripped: + in_html_comment = False + continue # RST skip block (e.g. .. raw::): discard all indented content if in_rst_skip_block: if not stripped or line[0] in (" ", "\t"): @@ -201,8 +212,26 @@ def generate_combined_markdown(app, exception): if _RST_CODE_BLOCK_RE.match(stripped): in_rst_code_block = True continue - if not stripped or is_prose_line(line): + # HTML comment open (): discard opener and enter state + if stripped.startswith("" not in stripped: + in_html_comment = True + continue + # Multi-line HTML opening tag: skip continuation lines until > + if in_html_open_tag: + if ">" in stripped: + in_html_open_tag = False + continue + # Detect HTML opening tags that wrap across lines (no > on this line) + if _HTML_TAG_RE.match(stripped) and ">" not in stripped: + in_html_open_tag = True + continue + if not stripped: kept.append(line) + elif is_prose_line(line): + # Strip trailing HTML close tags (e.g. "See the guide.

") + cleaned = _TRAILING_HTML_CLOSE_RE.sub("", line).rstrip() + kept.append(cleaned if cleaned.strip() else line) cleaned = "\n".join(kept) combined.append(f"\n\n---\n\n# {relative}\n") From 7a2083691743f75206c087a67a1ac974a86aa654 Mon Sep 17 00:00:00 2001 From: Kiss Date: Fri, 29 May 2026 14:19:54 +0200 Subject: [PATCH 6/6] llms: drop punctuation-only lines after stripping trailing HTML close tags Lines like ".

" from sphinx-design grid cards pass _is_prose_line because they start with ".". After stripping "

", the remaining content is a bare "." with no word characters and should be discarded. Co-Authored-By: Claude Sonnet 4.6 --- docs/conf.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7b0bf18..7b1b4a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -231,7 +231,15 @@ def generate_combined_markdown(app, exception): elif is_prose_line(line): # Strip trailing HTML close tags (e.g. "See the guide.

") cleaned = _TRAILING_HTML_CLOSE_RE.sub("", line).rstrip() - kept.append(cleaned if cleaned.strip() else line) + cleaned_stripped = cleaned.strip() + if not cleaned_stripped: + # Entire line was HTML close tags — keep original (shouldn't + # normally reach here since _is_prose_line filters HTML). + kept.append(line) + elif re.search(r"\w", cleaned_stripped): + # Line has real word content after stripping close tags. + kept.append(cleaned) + # else: only punctuation remains (e.g. bare ".") — discard. cleaned = "\n".join(kept) combined.append(f"\n\n---\n\n# {relative}\n")