diff --git a/docs/conf.py b/docs/conf.py index 114f235b..f9f62c6b 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,238 @@ # 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'] + +html_extra_path = ["llms.txt"] + +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-]*\)=$") + +# 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)::") + +# 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. "
", "

", " block + in_html_open_tag = False # inside a multi-line HTML opening tag + 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 + # 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"): + 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 + continue + # 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() + 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") + 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 00000000..d76550db --- /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. + +---