From 4c099c45f716a2a46ae38561c75bb2bb97cfcb6b Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Tue, 19 May 2026 11:59:02 +0200
Subject: [PATCH 1/6] Add markdown button and make llms.txt available

---
 docs/conf.py  | 138 ++++++++++++++++++++++++++++++++++++++++++++++----
 docs/llms.txt |  16 ++++++
 2 files changed, 145 insertions(+), 9 deletions(-)
 create mode 100644 docs/llms.txt

diff --git a/docs/conf.py b/docs/conf.py
index 114f235ba..8fc1735a6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,9 +1,6 @@
-# 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
+from pathlib import Path
 
 external_projects_local_file = "projects.yaml"
 external_projects_remote_repository = ""
@@ -11,6 +8,11 @@
 external_projects = []
 external_projects_current_project = "k8s-device-plugin"
 
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "instinct.docs.amd.com")
+html_context = {}
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
+
 project = "AMD Kubernetes Device Plugin Documentation"
 version = "1.3.1"
 release = version
@@ -21,12 +23,130 @@
 # Required settings
 html_theme = "rocm_docs_theme"
 html_theme_options = {
-    "flavor": "instinct"
+    "flavor": "instinct",
+    "link_main_doc": True,
+    "use_download_button": True,
 }
 extensions = ["rocm_docs"]
 
 external_toc_path = "./sphinx/_toc.yml"
 
-extensions = ["rocm_docs"]
-
 exclude_patterns = ['.venv']
+
+import re
+
+EXCLUDED_DIRS = {
+    "_build",
+    "_templates",
+    "_static",
+    ".git",
+    ".venv",
+    "vendor",
+}
+
+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. ".</p>")
+    if re.search(r"</?[a-zA-Z]", 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.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 Device Plugin for Kubernetes")
+
+    all_files = sorted(docs_root.rglob("*.md"))
+
+    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)
diff --git a/docs/llms.txt b/docs/llms.txt
new file mode 100644
index 000000000..d76550db6
--- /dev/null
+++ b/docs/llms.txt
@@ -0,0 +1,16 @@
+# AMD GPU Device Plugin for Kubernetes
+
+> Enable AMD GPUs as schedulable resources in Kubernetes clusters. The device plugin implements the Kubernetes Device Plugin API, exposes AMD GPUs as `amd.com/gpu` resources, provides automated node labeling with GPU properties, and supports topology-aware GPU allocation for optimal workload performance.
+
+## User guide
+
+- [Installation](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/user-guide/installation.html): Install the AMD GPU device plugin on a Kubernetes cluster using kubectl or Helm, with options for standard deployment, init container, health check monitoring, or the AMD GPU Operator.
+- [Configuration](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/user-guide/configuration.html): Configure the device plugin using environment variables, command-line flags, and YAML configuration files, including resource naming strategies for GPU partitioning.
+- [Example workloads](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/user-guide/examples.html): Run PyTorch and JAX workloads on AMD GPUs in Kubernetes, including single-GPU, multi-GPU, and non-privileged pod configurations.
+- [Resource allocation](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/user-guide/resource-allocation.html): Understand the best-effort topology-aware GPU allocation policy, which selects GPU sets based on XGMI/PCIe link type, NUMA affinity, and partition locality.
+
+## Contributing
+
+- [Development guidelines](https://instinct.docs.amd.com/projects/k8s-device-plugin/en/latest/contributing/development.html): Set up a development environment, follow the branching and pull request workflow, and understand the code review process for contributing to the device plugin.
+
+---

From 15055557b96ab1b8a0c1f1230e74a6016d8da0b1 Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Thu, 21 May 2026 10:48:10 +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 8fc1735a6..266cb249f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -33,6 +33,8 @@
 
 exclude_patterns = ['.venv']
 
+html_extra_path = ["llms.txt"]
+
 import re
 
 EXCLUDED_DIRS = {
@@ -73,6 +75,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
 
 
@@ -95,6 +100,15 @@ def is_prose_line(line: str) -> bool:
     # 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
 
 
@@ -103,7 +117,7 @@ def generate_combined_markdown(app, exception):
         return
 
     docs_root = Path(app.srcdir)
-    output_file = Path(app.outdir) / "llms.txt"
+    output_file = Path(app.outdir) / "llms-full.txt"
     base_file = docs_root / "llms.txt"
 
     combined = []
@@ -114,7 +128,9 @@ def generate_combined_markdown(app, exception):
     else:
         combined.append("# AMD GPU Device Plugin for Kubernetes")
 
-    all_files = sorted(docs_root.rglob("*.md"))
+    all_files = sorted(
+        list(docs_root.rglob("*.md")) + list(docs_root.rglob("*.rst"))
+    )
 
     for doc_file in all_files:
         if should_skip(doc_file):

From b25548d312fd6b5e0d8b26e1b5d2b8c5f284612f Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Fri, 29 May 2026 11:56:21 +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 266cb249f..117f75d75 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -78,6 +78,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
 
 
@@ -97,14 +100,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. ".</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):
+    # 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):
@@ -151,10 +153,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 661c532bac0195ba91f5715027518932e9a624e9 Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Fri, 29 May 2026 13:05:24 +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 117f75d75..a912852b5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,7 +63,6 @@
     ":header-rows:",
     ":alt:",
     "+++",
-    "<",
     "-->",
     "{bdg-",
 )
@@ -81,6 +80,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. "<div>", "</p>", "<!--") but NOT RST hyperlink URL
+# continuation lines (e.g. "<https://...>`_").  The negative lookahead excludes
+# URL schemes so that multi-line RST inline hyperlinks are preserved.
+_HTML_TAG_RE = re.compile(r"^<(?!https?://|ftp://|mailto:)[a-zA-Z/!]")
+
 MIN_PROSE_LINES = 10
 
 
@@ -100,13 +110,24 @@ 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 markdown table separator rows (e.g. "|---|---|", "| :--- | ---: |")
+    if _MD_TABLE_SEP_RE.match(stripped):
+        return False
+    # Drop HTML tags (e.g. "<div>", "</p>") but keep RST hyperlink URL
+    # continuation lines (e.g. "<https://rocm.docs.amd.com/...>`_")
+    if _HTML_TAG_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):
+    # Drop YAML frontmatter key-value pairs (e.g. "description lang=en": "text")
+    if stripped.startswith('"') and re.match(r'^"[^"]+"\s*:', stripped):
+        return False
+    # Drop RST field list items (e.g. ":type: int") and extended RST meta
+    # options (e.g. ":description lang=en: text"). Excludes inline roles at line
+    # start (e.g. ":cpp:func:`hipMalloc` returns..." or ":ref:`foo <bar>` describes...")
+    # because those are followed by a backtick, not a space or end-of-line.
+    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):
@@ -155,6 +176,7 @@ def generate_combined_markdown(app, exception):
         relative = doc_file.relative_to(docs_root)
         in_backtick_fence = False
         in_rst_code_block = False
+        in_rst_skip_block = False
         kept = []
         for line in lines:
             stripped = line.strip()
@@ -166,12 +188,21 @@ def generate_combined_markdown(app, exception):
             if in_backtick_fence:
                 kept.append(line)
                 continue
+            # RST skip block (e.g. .. raw::): discard all indented content
+            if in_rst_skip_block:
+                if not stripped or line[0] in (" ", "\t"):
+                    continue
+                in_rst_skip_block = False
             # 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 raw block: enter and discard both the directive and its body
+            if _RST_SKIP_BLOCK_RE.match(stripped):
+                in_rst_skip_block = True
+                continue
             # RST code block: enter on directive line (directive itself is dropped)
             if _RST_CODE_BLOCK_RE.match(stripped):
                 in_rst_code_block = True

From f38e3f182453a189b2b5d39585346685cba7cdd8 Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Fri, 29 May 2026 13:51:15 +0200
Subject: [PATCH 5/6] sync llms filter fixes from rocm-docs-core

- Add _TRAILING_HTML_CLOSE_RE to strip trailing HTML close tags from prose lines
- Add in_html_comment state to discard HTML comment blocks (<!-- ... -->)
- 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 a912852b5..99d0c4730 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,6 +91,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.</p>", "See the guide.</li></ul>").
+_TRAILING_HTML_CLOSE_RE = re.compile(r"(</[a-zA-Z]+>)+\s*$")
+
 MIN_PROSE_LINES = 10
 
 
@@ -177,6 +181,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()
@@ -188,6 +194,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"):
@@ -207,8 +218,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("<!--"):
+                if "-->" 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.</p>")
+                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 83663a95443b762b42c3cce237bcec271ff6450a Mon Sep 17 00:00:00 2001
From: Kiss <istvan.kiss@amd.com>
Date: Fri, 29 May 2026 14:19:48 +0200
Subject: [PATCH 6/6] llms: drop punctuation-only lines after stripping
 trailing HTML close tags

Lines like ".</p>" from sphinx-design grid cards pass _is_prose_line
because they start with ".". After stripping "</p>", the remaining
content is a bare "." with no word characters and should be discarded.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/conf.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 99d0c4730..f9f62c6bf 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -237,7 +237,15 @@ def generate_combined_markdown(app, exception):
             elif is_prose_line(line):
                 # Strip trailing HTML close tags (e.g. "See the guide.</p>")
                 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")