Add markdown button and make llms.txt available

docs/conf.py

@@ -1,5 +1,7 @@
 """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 = {}
@@ -27,7 +29,7 @@
 ol_version_numbers = ['10.1', '9.7', '8.10']
 rl_version_numbers = ['9.7']
 
-html_context = {
+html_context.update({
     "ubuntu_version_numbers" : ubuntu_version_numbers,
     "debian_version_numbers" : debian_version_numbers,
     "sles_version_numbers" : sles_version_numbers,
@@ -36,7 +38,7 @@
     "ol_release_version_numbers" : ol_release_version_numbers,
     "ol_version_numbers" : ol_version_numbers,
     "rl_version_numbers" : rl_version_numbers
-}
+})
 
 
 # Required settings
@@ -45,6 +47,7 @@
     "flavor": "amdgpu",
     "announcement": f"<a id='rocm-banner' href='https://instinct.docs.amd.com/projects/amdgpu-docs/en/31.20.0-preview/'>AMD GPU Driver 31.20.0</a> is a technology preview intended for use only with <a id='rocm-banner' href='https://rocm.docs.amd.com/en/7.12.0-preview/index.html'>AMD ROCm 7.12.0 technology preview</a>. For production use, continue to use AMD GPU Driver {version} documentation.",
     "link_main_doc": True,
+    "use_download_button": True,
     # Add any additional theme options here
 }
 extensions = [
@@ -58,6 +61,138 @@
 
 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 "(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
+
+
+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. ".</p>")
+    if re.search(r"</?[a-zA-Z]", 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 not in MARKUP_PREFIXES
+    if re.match(r"^:[A-Za-z]", 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 GPU Driver (amdgpu)")
+
+    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)
+        cleaned = "\n".join(
+            line for line in lines
+            if line.strip() == "" or is_prose_line(line)
+        )
+
+        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.connect("build-finished", generate_combined_markdown)
+
 # Add the following replacements to every RST file.
 rst_prolog = f"""
 .. |version| replace:: {version}

docs/llms.txt

@@ -0,0 +1,30 @@
+# AMD GPU Driver (amdgpu)
+
+> Install, configure, and optimize the AMD GPU driver (amdgpu) for AMD Instinct and Radeon GPUs on Linux. Covers package manager installation across major distributions, post-install steps, system optimization tuning guides for MI300X and MI300A, GPU partitioning, and conceptual reference for IOMMU, PCIe atomics, and resource oversubscription.
+
+## Install AMD GPU Driver
+
+- [Prerequisites](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/install/detailed-install/prerequisites.html): System requirements and prerequisites before installing the AMD GPU driver, including kernel version and dependency checks.
+- [Install via package manager](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/install/package-manager-index.html): Install the AMD GPU driver using native package managers on Ubuntu, Debian, RHEL, Oracle Linux, Rocky Linux, and SUSE Linux Enterprise Server.
+- [Post-install instructions](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/install/detailed-install/post-install.html): Configure user groups, verify driver loading, and complete required post-installation steps after installing the AMD GPU driver.
+
+## How to
+
+- [System optimization](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/system-optimization/index.html): Hardware and OS tuning guides for AMD Instinct GPU workloads, including BIOS settings, GRUB configuration, NBIO tuning, and environment variable recommendations.
+- [MI300X system optimization](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/system-optimization/mi300x.html): AMD Instinct MI300X-specific system settings for HPC and AI workloads, including BIOS, NBIO, and ROCm environment variable tuning.
+- [MI300A system optimization](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/system-optimization/mi300a.html): AMD Instinct MI300A APU-specific system tuning for high-performance computing workloads.
+- [MI200 system optimization](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/system-optimization/mi200.html): Performance and system tuning guide for AMD Instinct MI200 series GPUs.
+- [MI100 system optimization](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/system-optimization/mi100.html): Performance and system tuning guide for AMD Instinct MI100 GPUs.
+- [MI300X GPU partitioning overview](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/gpu-partitioning/mi300x/overview.html): Overview of GPU partitioning capabilities on AMD Instinct MI300X, including partition modes and resource isolation.
+- [MI300X GPU partitioning requirements](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/gpu-partitioning/mi300x/requirements.html): Hardware and software requirements for enabling GPU partitioning on AMD Instinct MI300X.
+- [MI300X GPU partitioning quick start](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/gpu-partitioning/mi300x/quick-start-guide.html): Step-by-step guide to configuring and activating GPU partitioning on AMD Instinct MI300X.
+- [MI300X GPU partitioning troubleshooting](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/gpu-partitioning/mi300x/troubleshooting.html): Diagnose and resolve common issues when configuring GPU partitioning on AMD Instinct MI300X.
+- [MI300A GPU partitioning overview](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/gpu-partitioning/mi300a/overview.html): Overview of GPU partitioning on the AMD Instinct MI300A APU.
+
+## Conceptual
+
+- [IOMMU](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/conceptual/iommu.html): How Input-Output Memory Management Unit (IOMMU) affects AMD GPU DMA operations, PCIe topology, and xGMI configurations.
+- [PCIe atomics](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/conceptual/pcie-atomics.html): PCIe atomic operations support in ROCm and their role in GPU peer-to-peer communication.
+- [Oversubscription](https://instinct.docs.amd.com/projects/amdgpu-docs/en/latest/conceptual/oversubscription.html): Considerations and tradeoffs when oversubscribing hardware resources with AMD GPU workloads.
+
+---