ci: add linting workflow for docs (markdown + spelling)

.github/workflows/linting.yml

@@ -0,0 +1,37 @@
+name: Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  docs-lint:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install markdownlint-cli2
+        run: npm install -g markdownlint-cli2
+
+      - name: Set up Python and pyspelling
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install spelling dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y aspell aspell-en
+          pip install pyspelling
+
+      - name: Run docs lint (markdown + spelling)
+        run: make docs-lint

.markdownlint.yaml

@@ -0,0 +1,54 @@
+# Match rocm-docs-core linting rules
+# Relaxed for existing docs; tighten over time if desired.
+default: true
+
+# Line length (often too strict for prose/tables)
+MD013: false
+
+# First heading h1, first line (conflicts with multi-section READMEs)
+MD041: false
+
+# Inline HTML / bare URLs (allow in docs)
+MD033: false
+MD034: false
+
+# Duplicate headings (only warn across siblings)
+MD024:
+  siblings_only: true
+
+# Heading punctuation
+MD026:
+  punctuation: ".,;:!"
+
+# --- Relaxed for open-source docs (high churn, many contributors) ---
+
+# Multiple top-level headings (READMEs/docs often use several # sections)
+MD025: false
+
+# Heading level increment (allow ## then #### without ###)
+MD001: false
+
+# Blank lines around headings and code blocks (readability; skip for legacy)
+MD022: false
+MD031: false
+
+# Blank lines around lists
+MD032: false
+
+# Ordered list prefix style (1/2/3 vs 1/1/1)
+MD029: false
+
+# Fenced code block language (syntax highlighting; optional)
+MD040: false
+
+# Table column alignment (cosmetic)
+MD060: false
+
+# Unordered list style (dash vs asterisk)
+MD004: false
+
+# Multiple consecutive blank lines
+MD012: false
+
+# Trailing spaces (noisy in legacy docs; enable later for new edits)
+MD009: false

.spellcheck.yaml

@@ -0,0 +1,105 @@
+# BSD 3-Clause License
+#
+# Copyright (c) 2017-2022, Pytorch contributors
+# All rights reserved.
+# Modifications Copyright (c) 2023, Advanced Micro Devices, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+matrix:
+- name: Markdown
+  sources:
+  - ['docs/**/*.md']
+  expect_match: false
+  aspell:
+    lang: en
+  dictionary:
+    wordlists:
+    - .wordlist.txt
+  pipeline:
+  - pyspelling.filters.context:
+      context_visible_first: true
+      delimiters:
+      # Manual disabling via: #spellcheck-disable
+      - open : '^ *<!-- *spellcheck-disable *-->$'
+        content: '[\s\S]*?'
+        close: '^ *<!-- *spellcheck-enable *-->$'
+      # Ignore URLs in [text](URL)
+      - open : '\[[^]]*?]\('
+        content: '[^)]*?'
+        close: '\)'
+      # Ignore out-of-line URL references in [text][reference-name]
+      - open : '\[[^\]]*?\]\['
+        content: '[^\]]*?'
+        close: '\]'
+      # Ignore out-of-line URL definitions
+      - open : '^ {0,3}\[[^\]]*?\]:\s*\S+'
+        close: '$'
+      # Ignore URLs in <URL>
+      - open : '\<'
+        content: '[^]]*?'
+        close: '\>'
+      # Ignore text in backtick code blocks.
+      - open : '(?s)^(?P<open> *`{3,})[^\n]*$'
+        close: '^(?P=open)$'
+      # Ignore text between inline back ticks
+      - open : '(?P<open>`+)'
+        content: '[^\n]+'
+        close: '(?P=open)'
+      # Ignore block classes and extra in :::{class} extra
+      - open : '^ *:{3,}'
+        content: '[^\n]+'
+        close: ''
+      # Ignore keys in :property: key
+      - open : '^ *:[^\n:]*: +'
+        content: '[^\n]+'
+        close: '$'
+      # Ignore properties in :property:
+      - open : '^ *:'
+        close: ':'
+      # Ignore tag in (tag)=
+      - open : '('
+        content: '[^\n]+'
+        close: ')=$'
+  - pyspelling.filters.url:
+- name: reST
+  sources:
+  - ['docs/**/*.rst']
+  expect_match: false
+  aspell:
+    lang: en
+  dictionary:
+    wordlists:
+    - .wordlist.txt
+  pipeline:
+  - pyspelling.filters.markdown:
+  - pyspelling.filters.html:
+      comments: false
+      ignores:
+      - code
+      - pre
+  - pyspelling.filters.url:

.wordlist.txt

@@ -907,3 +907,104 @@ datacenter
 programmability
 uptime
 TPX
+aG
+AINIC
+autoremove
+barebones
+baseurl
+cdi
+CDI
+CLIs
+CLK
+conf
+containerd
+containerd's
+cpus
+ctk
+dearmor
+dmesg
+dnf
+dri
+Dockerfiles
+dpkg
+EOF
+Enroot
+enroot
+gdrcopy
+GID
+gpg
+gpgcheck
+gpgkey
+Gres
+gpu
+gpus
+gres
+GPUDirect
+headnode
+html
+impactful
+integrations
+io
+jq
+journalctl
+json
+keyrings
+Kubernetes
+libelf
+libssl
+libudev
+LOGNAME
+loopback
+lsmod
+modprobe
+mycontainer
+myst
+natively
+nerdctl
+newgrp
+ntasks
+Numbat
+nvidia
+OCI
+nvslurm
+OpenIB
+perf
+PMIx
+png
+QoS
+Podman
+podman
+Pollara
+px
+pytorch
+pyxis
+Pyxis
+renderD
+roce
+RoCEv
+routable
+rsmi
+runtime's
+runtimeArgs
+RUNC
+sbatch
+SBATCH
+slurm
+slurmctld
+SLURM
+slurmd
+sqsh
+sudo
+systemctl
+tensorflow
+Toolkit's
+ubuntu
+uname
+unpartitioned
+usecase
+usermod
+usr
+UUIDs
+warmup
+wget
+AutoDetect

Makefile

@@ -200,6 +200,39 @@ vet: ## Run go vet against code.
 test: ## Run go test against code.
 	AMD_CTK_PATH=$(CURDIR)/bin/$(BIN_DIRECTORY_SUFFIX)/amd-ctk go test -v ./...
 
+# Docs lint (Markdown + spelling; matches CI linting checks)
+DOCS_MARKDOWNLINTCONFIG ?= .markdownlint.yaml
+DOCS_MD_GLOB ?= "**/*.md"
+DOCS_SPELLCHECK_CONFIG ?= .spellcheck.yaml
+
+.PHONY: docs-lint-markdown
+docs-lint-markdown: ## Run markdownlint on all Markdown files.
+	markdownlint-cli2 $(DOCS_MD_GLOB) --config $(DOCS_MARKDOWNLINTCONFIG)
+
+.PHONY: docs-lint-spelling
+docs-lint-spelling: ## Run pyspelling (spellcheck) using .spellcheck.yaml.
+	pyspelling -c $(DOCS_SPELLCHECK_CONFIG)
+
+.PHONY: docs-lint
+docs-lint: ## Run docs Markdown lint + spelling (full docs lint, same as CI).
+	$(MAKE) docs-lint-markdown
+	$(MAKE) docs-lint-spelling
+
+# Run docs lint inside a container (no local Node/Python/aspell needed)
+DOCS_LINT_IMAGE ?= $(DOCKER_REGISTRY)/container-toolkit-docs-lint:latest
+.PHONY: docs-lint-docker docs-lint-docker-build docs-lint-docker-push
+docs-lint-docker: ## Run docs lint in Docker (markdown + spelling). Image must exist locally or use docs-lint-docker-pull.
+	docker run --rm -v $(CURDIR):/repo -w /repo $(DOCS_LINT_IMAGE) docs-lint
+
+docs-lint-docker-pull: ## Pull the docs-lint image from the registry (run once or to update).
+	docker pull $(DOCS_LINT_IMAGE)
+
+docs-lint-docker-build: ## Build the docs-lint image locally (for Dockerfile changes or first-time setup).
+	docker build -t $(DOCS_LINT_IMAGE) -f $(CURDIR)/tools/docs-lint/Dockerfile $(CURDIR)/tools/docs-lint
+
+docs-lint-docker-push: docs-lint-docker-build ## Build and push the docs-lint image to the registry (for maintainers/CI).
+	docker push $(DOCS_LINT_IMAGE)
+
 GOLANGCI_LINT = $(shell pwd)/bin/golangci-lint
 .PHONY: golangci-lint
 golangci-lint: ## Download golangci-lint locally if necessary.

README.md

@@ -1,7 +1,7 @@
 # Overview
 AMD Container Toolkit offers tools to streamline the use of AMD GPUs with containers. The toolkit includes the following packages.
 - ```amd-container-runtime``` - The AMD Container Runtime
--  ```amd-ctk``` - The AMD Container Toolkit CLI
+- ```amd-ctk``` - The AMD Container Toolkit CLI
 
 # Requirements
 - Ubuntu 22.04 or 24.04, or RHEL/CentOS 9

tools/docs-lint/Dockerfile

@@ -0,0 +1,29 @@
+# Minimal image for running docs lint (markdownlint + pyspelling) locally.
+# Use: make docs-lint-docker (from repo root)
+ARG BUILD_BASE_IMAGE=ubuntu:22.04
+FROM ${BUILD_BASE_IMAGE}
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Node.js 22.x (markdownlint-cli2 requires Node >= 20)
+RUN apt-get update && apt-get install -y curl ca-certificates && \
+    curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+RUN apt-get update && apt-get install -y \
+    make \
+    python3 \
+    python3-pip \
+    aspell \
+    aspell-en \
+    nodejs \
+    git \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+RUN npm install markdownlint-cli2 --global
+RUN pip3 install pyspelling
+
+WORKDIR /repo
+
+ENTRYPOINT ["make"]
+CMD ["docs-lint"]