Add markdown download button and make llms.txt available

docs/conf.py

@@ -1,6 +1,7 @@
 """Configuration file for the Sphinx documentation builder."""
 import os
-from sphinx import addnodes
+import re
+from pathlib import Path
 
 external_projects_remote_repository = ""
 external_projects_current_project = "dcgpu"
@@ -20,10 +21,12 @@
 copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
 
 # Required settings
+html_copy_source = True
 html_theme = "rocm_docs_theme"
 html_theme_options = {
     "flavor": "instinct",
     "link_main_doc": True,
+    "use_download_button": True,
     "nav_secondary_items": {
         "Community": "https://github.com/ROCm/ROCm/discussions",
         "Blogs": "https://rocm.blogs.amd.com/",
@@ -43,5 +46,158 @@
 
 exclude_patterns = ['.venv']
 
+html_extra_path = ["llms.txt"]
+
+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 "(gpu-arch-documentation)="
+_ANCHOR_LABEL_RE = re.compile(r"^\(\w[\w-]*\)=$")
+
+# 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
+
+
+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. "(gpu-arch-documentation)=")
+    if _ANCHOR_LABEL_RE.match(stripped):
+        return False
+    # Drop RST directives, comments, hyperlink targets, and substitution definitions
+    if stripped.startswith(".."):
+        return False
+    # Drop RST field list items (e.g. ":type: int") and MyST directive options without
+    # a leading colon (e.g. "align: center"). Excludes inline roles at line start
+    # (e.g. ":cpp:func:`hipMalloc` returns..." or ":ref:`foo <bar>` 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):
+        return False
+    return True
+
+
+def generate_combined_markdown(app, exception):
+    if exception:
+        return
+
+    docs_root = Path(app.srcdir)
+    output_file = Path(app.outdir) / "llms-full.txt"
+    base_file = docs_root / "llms.txt"
+
+    combined = []
+
+    if base_file.exists():
+        base_text = base_file.read_text(encoding="utf-8").rstrip().rstrip("-").rstrip()
+        combined.append(base_text)
+    else:
+        combined.append("# AMD Instinct Data Center GPU Documentation")
+
+    all_files = sorted(
+        list(docs_root.rglob("*.md")) + list(docs_root.rglob("*.rst"))
+    )
+
+    for doc_file in all_files:
+        if should_skip(doc_file):
+            continue
+
+        if doc_file == base_file:
+            continue
+
+        try:
+            content = doc_file.read_text(encoding="utf-8")
+        except Exception:
+            continue
+
+        lines = content.splitlines()
+        prose_lines = [line for line in lines if is_prose_line(line)]
+
+        if len(prose_lines) < MIN_PROSE_LINES:
+            continue
+
+        relative = doc_file.relative_to(docs_root)
+        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())
+
+    output_file.write_text(
+        "\n".join(combined) + "\n",
+        encoding="utf-8",
+    )
+
 def setup(app):
     app.add_css_file("css/index.css")
+    app.connect("build-finished", generate_combined_markdown)

docs/llms.txt

@@ -0,0 +1,83 @@
+# AMD Instinct Data Center GPU Documentation
+
+> Comprehensive guides and technical documentation for deploying AMD Instinct Data Center GPUs in enterprise environments. Covers system administration, cluster management, monitoring, and operational best practices for HPC and AI workloads. For API documentation and the ROCm software stack, see https://rocm.docs.amd.com.
+
+## GPU architecture
+
+- [AMD Instinct GPU architecture overview](https://instinct.docs.amd.com/en/latest/gpu-arch/gpu-arch.html): Microarchitecture overview of AMD Instinct MI350, MI300, MI250, and MI100 GPU accelerators.
+- [AMD Instinct MI350](https://instinct.docs.amd.com/en/latest/gpu-arch/mi350.html): Architecture and specifications for the MI350 series.
+- [AMD Instinct MI300](https://instinct.docs.amd.com/en/latest/gpu-arch/mi300.html): Architecture and specifications for the MI300 series, including MI300X and MI300A.
+- [AMD Instinct MI250](https://instinct.docs.amd.com/en/latest/gpu-arch/mi250.html): Architecture and specifications for the MI250 series.
+- [AMD Instinct MI100](https://instinct.docs.amd.com/en/latest/gpu-arch/mi100.html): Architecture and specifications for the MI100 series.
+
+## System administration
+
+### Bare metal
+
+- [AMD GPU Driver (amdgpu)](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/): Install and configure the AMD GPU driver. Covers logging and error codes.
+- [AMD Instinct Customer Acceptance Guide](https://instinct.docs.amd.com/projects/system-acceptance/en/latest/): Configure, validate, benchmark, and baseline AMD Instinct GPUs.
+- [AMD SMI](https://rocm.docs.amd.com/projects/amdsmi/en/latest/): System management interface for monitoring and managing AMD GPUs.
+- [ROCm Validation Suite](https://rocm.docs.amd.com/projects/ROCmValidationSuite/en/latest/): System validation and diagnostics.
+- [Cluster Validation Suite](https://rocm.docs.amd.com/projects/cvs/en/latest/): Test scripts to validate AMD AI clusters.
+
+### Containers and orchestration
+
+- [AMD GPU Operator](https://instinct.docs.amd.com/projects/gpu-operator/en/latest/): Deploy and manage AMD Instinct GPUs within Kubernetes clusters.
+- [Network Operator](https://instinct.docs.amd.com/projects/network-operator/en/main/): Use AMD AINICs in Kubernetes environments.
+- [Kubernetes Device Plugin](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/): Register AMD GPUs to Kubernetes container clusters.
+- [Device Metrics Exporter](https://instinct.docs.amd.com/projects/device-metrics-exporter/en/latest/): Prometheus-format GPU metrics collection.
+- [AMD Container Toolkit](https://instinct.docs.amd.com/projects/container-toolkit/en/latest/): Integrate AMD Instinct GPUs with Docker.
+
+### Cluster management
+
+- [Cluster Networking](https://instinct.docs.amd.com/projects/gpu-cluster-networking/en/latest/): Optimize networking for Instinct GPU applications.
+
+### Cloud
+
+- [AMD Instinct GPUs on Azure](https://instinct.docs.amd.com/projects/instinct-azure/latest/): Get started with AMD Instinct on Microsoft Azure.
+
+### Virtualization
+
+- [AMD Instinct Virtualization Driver](https://instinct.docs.amd.com/projects/virt-drv/en/latest/): Virtualization driver for AMD Instinct GPUs.
+- [AMD SMI for Virtualization](https://instinct.docs.amd.com/projects/amd-smi-virt/en/latest/): Manage and monitor AMD virtualization-enabled GPUs.
+
+## Workloads
+
+### Computer vision
+
+- [Models and applications](https://instinct.docs.amd.com/en/latest/vision/ai.html): Design, train, and infer computer vision models on AMD Instinct GPUs.
+- [Image and video decoding](https://instinct.docs.amd.com/en/latest/vision/decode.html): Decode image and video formats using AMD Instinct GPUs.
+- [Image processing](https://instinct.docs.amd.com/en/latest/vision/preprocess.html): Eliminate image preprocessing bottlenecks with AMD Instinct GPUs.
+
+### Data science
+
+- [ROCm Data Science Toolkit (ROCm-DS)](https://instinct.docs.amd.com/en/latest/data-science/index.html): Accelerate data science workloads on AMD Instinct GPUs.
+- [hipDF](https://instinct.docs.amd.com/en/latest/data-science/hipDF.html): GPU-accelerated DataFrames for data manipulation and analysis.
+- [hipGRAPH](https://instinct.docs.amd.com/en/latest/data-science/hipGRAPH.html): Create and analyze graphs and complex networks on AMD Instinct GPUs.
+- [hipVS](https://instinct.docs.amd.com/en/latest/data-science/hipVS.html): Vector search operations on AMD Instinct GPUs.
+- [hipMM](https://instinct.docs.amd.com/en/latest/data-science/hipMM.html): Advanced memory management for ROCm-DS libraries.
+- [hipRAFT](https://instinct.docs.amd.com/en/latest/data-science/hipRAFT.html): Fundamental algorithms and primitives for ROCm-DS libraries.
+
+### Life science
+
+- [ROCm Toolkit for Life Science (ROCm-LS)](https://instinct.docs.amd.com/en/latest/life-science/index.html): Accelerate life science workloads on AMD Instinct GPUs.
+- [hipCIM](https://instinct.docs.amd.com/en/latest/life-science/hipCIM.html): N-dimensional image processing for medical imaging on AMD Instinct GPUs.
+- [MONAI](https://instinct.docs.amd.com/en/latest/life-science/MONAI.html): Train and deploy AI models for medical imaging on AMD Instinct GPUs.
+
+## ISV applications
+
+- [Ansys Fluent](https://instinct.docs.amd.com/en/latest/isv-apps/ansys-fluent.html): Computational fluid dynamics with AMD GPU acceleration.
+- [Ansys Mechanical](https://instinct.docs.amd.com/en/latest/isv-apps/ansys-mechanical.html): Structural simulation on AMD Instinct GPUs.
+- [Cadence Fidelity LES Solver](https://instinct.docs.amd.com/en/latest/isv-apps/cadence-fidelity.html): Computational fluid dynamics on AMD Instinct GPUs.
+- [Devito Codes DevitoPRO](https://instinct.docs.amd.com/en/latest/isv-apps/devito.html): Seismic imaging on AMD Instinct GPUs.
+- [Siemens Simcenter STAR-CCM+](https://instinct.docs.amd.com/en/latest/isv-apps/siemens.html): Multiphysics CFD simulation on AMD Instinct GPUs.
+- [Stone Ridge Technology ECHELON](https://instinct.docs.amd.com/en/latest/isv-apps/stone-ridge.html): Reservoir simulation on AMD Instinct GPUs.
+- [GSplat](https://instinct.docs.amd.com/en/latest/simulation/gsplat.html): Gaussian splatting on AMD Instinct MI300X.
+
+## Programming reference
+
+- [HIP C++](https://rocm.docs.amd.com/projects/HIP/en/latest/): HIP programming model and API for AMD GPUs.
+- [OpenMP](https://rocm.docs.amd.com/projects/llvm-project/en/latest/conceptual/openmp.html): OpenMP programming model for AMD GPUs.
+- [AMD SMI API](https://rocm.docs.amd.com/projects/amdsmi/en/latest/): Full AMD SMI API reference.
+
+---