diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml new file mode 100644 index 0000000..190a740 --- /dev/null +++ b/.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 diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..d886af9 --- /dev/null +++ b/.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 diff --git a/.spellcheck.yaml b/.spellcheck.yaml new file mode 100644 index 0000000..c22daa0 --- /dev/null +++ b/.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 : '^ *$' + content: '[\s\S]*?' + close: '^ *$' + # 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 + - open : '\<' + content: '[^]]*?' + close: '\>' + # Ignore text in backtick code blocks. + - open : '(?s)^(?P *`{3,})[^\n]*$' + close: '^(?P=open)$' + # Ignore text between inline back ticks + - open : '(?P`+)' + 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: \ No newline at end of file diff --git a/.wordlist.txt b/.wordlist.txt index f74a2de..5209368 100644 --- a/.wordlist.txt +++ b/.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 diff --git a/Makefile b/Makefile index 610d7b9..1d835a6 100644 --- a/Makefile +++ b/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. diff --git a/README.md b/README.md index b5c619a..4e83ed3 100644 --- a/README.md +++ b/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 diff --git a/tools/docs-lint/Dockerfile b/tools/docs-lint/Dockerfile new file mode 100644 index 0000000..74a6b4e --- /dev/null +++ b/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"]