diff --git a/.github/scripts/sync-styleguide-vale.sh b/.github/scripts/sync-styleguide-vale.sh new file mode 100755 index 000000000..ad190256c --- /dev/null +++ b/.github/scripts/sync-styleguide-vale.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# Sync canonical Vale rules and the PaperMoon vocab from the +# papermoonio/documentation-style-guide repository into this repo's +# styles/ directory. The synced files are gitignored — the canonical +# repo is the single source of truth. +# +# Usage: +# ./.github/scripts/sync-styleguide-vale.sh # sync from main +# ./.github/scripts/sync-styleguide-vale.sh # sync from a branch, tag, or sha +# +# Project-specific vocab (styles/config/vocabularies/Polkadot/) is +# managed in this repo and is NOT overwritten. + +set -euo pipefail + +REPO=papermoonio/documentation-style-guide +REF=${1:-main} + +repo_root=$(git rev-parse --show-toplevel) +cd "$repo_root" + +tmpdir=$(mktemp -d) +trap 'rm -rf "$tmpdir"' EXIT + +echo "Cloning $REPO@$REF..." +git clone --depth=1 --branch="$REF" --quiet "https://github.com/$REPO" "$tmpdir/styleguide" + +mkdir -p styles/PaperMoon styles/config/vocabularies/PaperMoon + +cp "$tmpdir/styleguide"/styles/PaperMoon/*.yml styles/PaperMoon/ +cp "$tmpdir/styleguide"/styles/config/vocabularies/PaperMoon/accept.txt \ + styles/config/vocabularies/PaperMoon/accept.txt + +echo "Synced Vale rules and PaperMoon vocab from $REPO@$REF." +echo "Run 'vale .' to lint." diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..37e838b51 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,48 @@ +name: Vale style check + +on: + pull_request: + paths: + - "**.md" + - ".vale.ini" + - "styles/config/vocabularies/Polkadot/**" + - ".github/scripts/sync-styleguide-vale.sh" + - ".github/workflows/vale.yml" + +permissions: + contents: read + checks: write + pull-requests: read + +jobs: + vale: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Sync canonical Vale rules from the PaperMoon styleguide + run: ./.github/scripts/sync-styleguide-vale.sh + + - name: List changed markdown files + id: changed + run: | + base="${{ github.event.pull_request.base.sha }}" + head="${{ github.event.pull_request.head.sha }}" + files=$(git diff --name-only --diff-filter=AM "$base...$head" -- '*.md' | tr '\n' ' ') + echo "files=$files" >> "$GITHUB_OUTPUT" + echo "Changed markdown files: $files" + + - name: Run Vale on changed files + if: steps.changed.outputs.files != '' + uses: errata-ai/vale-action@reviewdog + with: + files: ${{ steps.changed.outputs.files }} + # Advisory only: surface findings in the Checks tab without blocking + # merge or spamming inline review comments. Reruns on every push, so + # the check status always reflects the latest commit. + fail_on_error: false + reporter: github-pr-check + filter_mode: added + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index b7d7669c7..b0338f86e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,9 @@ scripts/__pycache__/* .github/instructions/kluster-code-verify.instructions.md .kluster + +# Vale rules and vocab synced from papermoonio/documentation-style-guide +# by .github/scripts/sync-styleguide-vale.sh (CI runs the script before linting). +# The canonical repo is the single source of truth — never commit copies. +styles/PaperMoon/ +styles/config/vocabularies/PaperMoon/ diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..cd94bdbe0 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,31 @@ +StylesPath = styles +MinAlertLevel = suggestion +Vocab = PaperMoon, Polkadot + +# Vale rules and the PaperMoon vocab in styles/PaperMoon/ and +# styles/config/vocabularies/PaperMoon/ are synced from the canonical +# papermoonio/documentation-style-guide repo and are gitignored. +# Run `./.github/scripts/sync-styleguide-vale.sh` before linting locally; +# CI runs the script automatically (see .github/workflows/vale.yml). +# +# To also lint against Google's style, run `vale sync` after adding: +# Packages = Google +# then add `Google` to the BasedOnStyles list below. + +[*.md] +BasedOnStyles = Vale, PaperMoon + +# Vale.Spelling (Hunspell) is disabled: this repo enforces house style, +# not spelling. On a deeply technical docs repo the spell-checker flags an +# endless tail of valid tool/package names (npm, toolchain, Turbopack, ...) +# with no typo-catching benefit worth the vocab-curation toil. The curated +# PaperMoon house-style rules and Vale.Repetition/Vale.Terms stay enabled. +Vale.Spelling = NO + +TokenIgnores = (?:dApp|TestNet|MainNet|ERC-\d+|JSON-RPC) +BlockIgnores = (?s) *(```.*?```) + +# AGENTS.md describes the rules and references banned content by name; +# it is not subject to its own rules. +[AGENTS.md] +BasedOnStyles = diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..0db584a43 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# AGENTS.md — polkadot-docs + +This file is loaded automatically by coding agents (Claude Code, Cursor, Codex, and any tool that respects the `AGENTS.md` convention) when they open this repository. Read it before generating or editing any documentation. + +## Style and authoring rules + +Documentation in this repository follows the **PaperMoon Documentation Style Guide**. The agent-loadable rule set lives in a separate repository so it can be shared across customers and updated independently: + +- **Canonical source**: [`papermoonio/documentation-style-guide/AGENTS.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/AGENTS.md) +- **Prose reference**: [`papermoonio/documentation-style-guide/style-guide.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md) +- **Reviewer checklist**: [`papermoonio/documentation-style-guide/checklist.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/checklist.md) + +**Read the canonical `AGENTS.md` before authoring.** It front-loads the rules that AI-generated documentation most often violates — list punctuation, bold misuse, em dashes, banned phrases, terminology, code-identifier backticks, identifier consistency, image filenames, and the "no redundant subheadings above lead-in lists" rule. The pre-output checklist at the bottom of that file is the last thing to run before returning a draft. + +## Linting + +Vale rules and the PaperMoon vocab are not copied into this repo — they are pulled from the canonical [`papermoonio/documentation-style-guide`](https://github.com/papermoonio/documentation-style-guide) repo on every CI run, and on demand for local linting. The single source of truth is the styleguide repo. + +```bash +./.github/scripts/sync-styleguide-vale.sh # pull canonical Vale rules + PaperMoon vocab +vale . # lint +``` + +The `styles/PaperMoon/` and `styles/config/vocabularies/PaperMoon/` directories are gitignored. Project-specific vocab lives in `styles/config/vocabularies/Polkadot/` and is committed. + +CI runs the sync script and then Vale against changed markdown files on every pull request (see `.github/workflows/vale.yml`). + +## Project-specific rules + +These supplement (and where they conflict, override) the canonical styleguide: + +- **Customer override on heading case**: This site uses Chicago title case per the styleguide default. +- **External links open in a new tab**: this is handled by the MkDocs plugin configured for this site. Do not add `{target=\_blank}` manually — the canonical styleguide also drops the manual rule. +- **Snippet includes**: Reusable code lives in `.snippets/code/` and is included via `--8<-- 'code/path/to/file.ext'`. Do not inline code that already exists as a snippet. +- **Variables**: `variables.yml` at the repo root holds shared version pins and identifiers. Reference via `{{ variable_name }}`. + +## Precedence + +When rules conflict: + +1. **This file** (`polkadot-docs/AGENTS.md`) — project-specific overrides win. +2. **PaperMoon canonical styleguide** — default. +3. **Google developer documentation style guide** — fallback for anything the PaperMoon guide does not cover. + +## How to use this in an agent session + +A typical session opens by reading this file, then fetching the canonical styleguide rules (the file at the GitHub URL above, or a local clone if present). Apply the rules during generation, not just at review time. Run the pre-output checklist from the canonical `AGENTS.md` before returning a draft. diff --git a/styles/config/vocabularies/Polkadot/accept.txt b/styles/config/vocabularies/Polkadot/accept.txt new file mode 100644 index 000000000..8f70b4088 --- /dev/null +++ b/styles/config/vocabularies/Polkadot/accept.txt @@ -0,0 +1,39 @@ +Polkadot +Kusama +Paseo +Westend +Moonbeam +Moonriver +Moonbase +parachain +parachains +parathread +parathreads +relay chain +relaychain +Substrate +collator +collators +nominator +nominators +validator +validators +extrinsic +extrinsics +pallet +pallets +runtime +runtimes +XCM +SDK +SS58 +Subxt +Dedot +Chopsticks +PAPI +Polkadot.js +omninode +Zombienet +Bulletin +ink +ScaleCodec