From de3d042d1b7951ab944fd2b389d5cab8f2a05f82 Mon Sep 17 00:00:00 2001 From: wenjie Date: Fri, 17 Apr 2026 13:45:39 +0800 Subject: [PATCH] chore(docs): add docs layout lint target and contributor guidance Introduce a lint-docs script and Makefile target for common documentation naming and placement checks. Expand docs/README.md with layout and translation conventions, and update CONTRIBUTING.md to point contributors to the new docs guidance and validation step. --- CONTRIBUTING.md | 7 +- Makefile | 11 ++- docs/README.md | 128 ++++++++++++++++++++++--- scripts/lint-docs.sh | 219 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 345 insertions(+), 20 deletions(-) create mode 100755 scripts/lint-docs.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbb6a6347..a78c41c36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,8 @@ We are committed to maintaining a welcoming and respectful community. Be kind, c For substantial new features, please open an issue first to discuss the design before writing code. This prevents wasted effort and ensures alignment with the project's direction. +For documentation contributions, prefer the layout and naming conventions in [`docs/README.md`](docs/README.md). Run `make lint-docs` after adding or moving Markdown files to catch common consistency issues early. + --- ## Getting Started @@ -64,7 +66,7 @@ For substantial new features, please open an issue first to discuss the design b ```bash make build # Build binary (runs go generate first) make generate # Run go generate only -make check # Full pre-commit check: deps + fmt + vet + test +make check # Full pre-commit check: deps + fmt + vet + test + docs consistency checks ``` ### Running Tests @@ -81,9 +83,10 @@ go test -bench=. -benchmem -run='^$' ./... # Run benchmarks make fmt # Format code make vet # Static analysis make lint # Full linter run +make lint-docs # Check common documentation layout and naming conventions ``` -All CI checks must pass before a PR can be merged. Run `make check` locally before pushing to catch issues early. +All CI checks must pass before a PR can be merged. Run `make check` locally before pushing to catch issues early, including the common docs consistency checks from `make lint-docs`. --- diff --git a/Makefile b/Makefile index afaa7c29a..c5d691c29 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: all build install uninstall clean help test build-all +.PHONY: all build install uninstall clean help test build-all lint-docs # Build variables BINARY_NAME=picoclaw @@ -308,9 +308,14 @@ test: generate fmt: @$(GOLANGCI_LINT) fmt +## lint-docs: Check common documentation layout and naming conventions +lint-docs: + @./scripts/lint-docs.sh + ## lint: Run linters lint: @$(GOLANGCI_LINT) run --build-tags $(GO_BUILD_TAGS) + @./scripts/lint-docs.sh ## fix: Fix linting issues fix: @@ -326,8 +331,8 @@ update-deps: @$(GO) get -u ./... @$(GO) mod tidy -## check: Run vet, fmt, and verify dependencies -check: deps fmt vet test +## check: Run deps, fmt, vet, tests, and docs consistency checks +check: deps fmt vet test lint-docs ## run: Build and run picoclaw run: build diff --git a/docs/README.md b/docs/README.md index 1153cfde5..0e5f38b4e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,21 +1,119 @@ # PicoClaw Documentation -Documentation is organized by document type first and language second. +PicoClaw documentation is organized by document type first and language second. -## Sections +This file describes the recommended documentation layout, how translated files should be named, and what `make lint-docs` currently checks locally. -- `project/`: project-level translated entry documents -- `guides/`: setup and usage guides -- `reference/`: reference material and configuration details -- `operations/`: debugging and troubleshooting -- `security/`: security-related documentation -- `architecture/`: architecture and internal design notes -- `channels/`: channel-specific integration guides -- `design/`: design proposals and investigations -- `migration/`: migration notes +These conventions are intended as contributor guidance for new or moved docs. Existing docs may still have historical exceptions, and `make lint-docs` only checks a common subset of the patterns described here. -## Language Naming +## Principles -- English documents use the base filename, for example `configuration.md` -- Translations use `..md`, for example `configuration.zh.md` -- Code-adjacent translated READMEs follow the same convention +- Choose the document type directory first. Do not create language buckets such as `docs/zh/` or `docs/fr/`. +- Keep each translated document next to its English source document. +- Use English as the base filename with no locale suffix. +- Use lowercase locale suffixes for translations, for example `configuration.zh.md` or `README.pt-br.md`. +- Keep module-specific docs next to the code they describe instead of moving them into `docs/`. + +## Recommended Directories + +- `README.md`: English project entry document at the repository root. +- `docs/project/`: translated project entry documents such as `README.zh.md` and `CONTRIBUTING.zh.md`. +- `docs/guides/`: setup and usage guides. +- `docs/reference/`: reference material and detailed configuration docs. +- `docs/operations/`: debugging and troubleshooting docs. +- `docs/security/`: security-related documentation. +- `docs/architecture/`: architecture and internal design notes. +- `docs/channels/`: channel-specific integration guides. +- `docs/design/`: design proposals and investigations. +- `docs/migration/`: migration notes. + +## Recommended Naming + +- English documents use the base filename: + - `README.md` + - `configuration.md` +- Translations use `..md`: + - `README.zh.md` + - `configuration.fr.md` + - `README.pt-br.md` +- Code-adjacent translated READMEs follow the same rule: + - `pkg/audio/asr/README.zh.md` + - `pkg/isolation/README.zh.md` + +## Common Patterns To Avoid + +- Root-level translated entry docs such as `README.zh.md` or `CONTRIBUTING.fr.md` + - Use `docs/project/README.zh.md` or `docs/project/CONTRIBUTING.fr.md` instead. +- Language directories under `docs/` such as `docs/zh/`, `docs/ZH/`, `docs/ja/`, or `docs/fr/` + - Use `docs//..md` instead. +- Nested locale buckets such as `docs/guides/zh/configuration.md` or `docs/channels/telegram/zh/README.md` + - Keep translations beside the English source file instead. +- Legacy translation filenames such as `README_zh.md` or `README_CN.md` + - Use `README.zh.md`. +- Non-canonical locale suffixes such as `configuration_zh.md` or `configuration.ZH.md` + - Use lowercase `..md`, for example `configuration.zh.md`. + +## Translation Placement + +- For docs under `docs/guides`, `docs/reference`, `docs/operations`, `docs/security`, `docs/architecture`, `docs/channels`, and `docs/migration`, keep translations beside the English source file. +- For project entry translations, keep translated files in `docs/project/` and keep the English source in the repository root. +- In most cases, each translated file should have an English source document: + - `docs/guides/configuration.zh.md` usually sits beside `docs/guides/configuration.md` + - `docs/project/README.zh.md` usually corresponds to `README.md` +- Exception: `docs/design/` may contain locale-specific working notes without an English source document. The naming rules still apply there. + +## Code-Adjacent Docs + +Keep documentation next to the implementation when it primarily describes a package, command, example, or subproject. + +Examples: + +- `pkg/**/README.md` +- `cmd/**/README.md` +- `web/README.md` +- `examples/**/README.md` + +These files still follow the same translation naming rules. + +## Adding a New Document + +1. Pick the correct document type directory. +2. Create the English source file first. +3. Add translated siblings after the English source exists when that source is part of the same docs set. +4. Update links from existing docs when the new doc becomes a navigation target. +5. Run `make lint-docs` locally when adding or moving docs. + +## Examples + +- New setup guide: + - `docs/guides/launcher-setup.md` + - `docs/guides/launcher-setup.zh.md` +- New security guide: + - `docs/security/token-rotation.md` +- New translated package README: + - `pkg/channels/README.zh.md` + +## Validation + +Run: + +```bash +make lint-docs +``` + +The local docs linter currently checks these common cases: + +- no root-level translated `README` or `CONTRIBUTING` files +- no `docs//` language buckets, regardless of case +- no nested locale buckets under typed docs directories +- no legacy `README_*.md` filenames +- no non-canonical translation-like filenames such as `_zh.md` or `.ZH.md` +- no extra Markdown files directly under `docs/` except `docs/README.md` +- every translated Markdown file has a matching English source file + - except for locale-specific working notes under `docs/design/` + +`make lint-docs` is a local consistency check for common naming and placement mistakes. It helps contributors stay close to the recommended layout, but it is not intended to describe every acceptable documentation pattern in the repository. + +When a check fails, `make lint-docs` prints the failing path, the reason, and a suggested fix. + +If you change these recommendations or want the local linter to reflect them more closely, update this file and `scripts/lint-docs.sh` together. diff --git a/scripts/lint-docs.sh b/scripts/lint-docs.sh new file mode 100755 index 000000000..7351298b6 --- /dev/null +++ b/scripts/lint-docs.sh @@ -0,0 +1,219 @@ +#!/usr/bin/env bash + +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +failures=0 + +error() { + local path="$1" + local reason="$2" + local suggestion="${3:-}" + + echo "docs lint: $path" >&2 + echo " reason: $reason" >&2 + if [[ -n "$suggestion" ]]; then + echo " fix: $suggestion" >&2 + fi + failures=1 +} + +lowercase() { + printf '%s' "$1" | tr '[:upper:]' '[:lower:]' +} + +suggest_noncanonical_translation_name() { + local path="$1" + local dir + local base + local stem + local locale + + dir="$(dirname "$path")" + base="$(basename "$path")" + + if [[ "$base" =~ ^(.+)_([A-Za-z]{2}(-[A-Za-z]{2})?)\.md$ ]]; then + stem="${BASH_REMATCH[1]}" + locale="$(lowercase "${BASH_REMATCH[2]}")" + printf '%s/%s.%s.md' "$dir" "$stem" "$locale" + return + fi + + if [[ "$base" =~ ^(.+)\.([A-Za-z]{2}(-[A-Za-z]{2})?)\.md$ ]]; then + stem="${BASH_REMATCH[1]}" + locale="$(lowercase "${BASH_REMATCH[2]}")" + printf '%s/%s.%s.md' "$dir" "$stem" "$locale" + return + fi + + printf 'rename it to use a lowercase ..md suffix beside the English source' +} + +suggest_docs_language_bucket_target() { + local path="$1" + local locale + local file + local name + local -a matches + + if [[ "$path" =~ ^docs/([A-Za-z]{2}(-[A-Za-z]{2})?)/.+\.md$ ]]; then + locale="$(lowercase "${BASH_REMATCH[1]}")" + file="$(basename "$path")" + name="${file%.md}" + mapfile -t matches < <(find docs/project docs/guides docs/reference docs/operations docs/security docs/architecture docs/channels docs/design docs/migration -type f -name "${name}.md" 2>/dev/null | sort) + if [[ "${#matches[@]}" -eq 1 ]]; then + printf '%s' "${matches[0]%.md}.${locale}.md" + return + fi + fi + + printf 'move it to a typed docs directory and rename it to ..md beside the English source' +} + +suggest_nested_locale_bucket_target() { + local path="$1" + local prefix + local locale + local rest + + if [[ "$path" =~ ^(docs/(project|guides|reference|operations|security|architecture|design|migration))/([A-Za-z]{2}(-[A-Za-z]{2})?)/(.*)\.md$ ]]; then + prefix="${BASH_REMATCH[1]}" + locale="$(lowercase "${BASH_REMATCH[3]}")" + rest="${BASH_REMATCH[5]}" + printf '%s/%s.%s.md' "$prefix" "$rest" "$locale" + return + fi + + if [[ "$path" =~ ^(docs/channels/[^/]+)/([A-Za-z]{2}(-[A-Za-z]{2})?)/(.*)\.md$ ]]; then + prefix="${BASH_REMATCH[1]}" + locale="$(lowercase "${BASH_REMATCH[2]}")" + rest="${BASH_REMATCH[4]}" + printf '%s/%s.%s.md' "$prefix" "$rest" "$locale" + return + fi + + printf 'move the file beside its English source and rename it to ..md' +} + +is_noncanonical_translation_name() { + local path="$1" + local base + + base="$(basename "$path")" + + [[ "$base" =~ ^.+_[A-Za-z]{2}(-[A-Za-z]{2})?\.md$ ]] && return 0 + [[ "$base" =~ ^.+\.[A-Z]{2}(-[A-Z]{2})?\.md$ ]] && return 0 + [[ "$base" =~ ^.+\.[a-z]{2}-[A-Z]{2}\.md$ ]] && return 0 + [[ "$base" =~ ^.+\.[A-Z]{2}-[a-z]{2}\.md$ ]] && return 0 + + return 1 +} + +is_noncanonical_locale_bucket() { + local path="$1" + + [[ "$path" =~ ^docs/(project|guides|reference|operations|security|architecture|design|migration)/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]] && return 0 + [[ "$path" =~ ^docs/channels/[^/]+/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]] && return 0 + return 1 +} + +is_root_docs_language_bucket() { + local path="$1" + [[ "$path" =~ ^docs/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]] +} + +is_translation_file() { + local path="$1" + [[ "$path" =~ ^(.+)\.([a-z]{2})(-[a-z]{2})?\.md$ ]] +} + +translation_base() { + local path="$1" + local locale="$2" + + if [[ "$path" == docs/project/* ]]; then + local rel="${path#docs/project/}" + echo "${rel%.$locale.md}.md" + return + fi + + echo "${path%.$locale.md}.md" +} + +while IFS= read -r path; do + [[ -f "$path" ]] || continue + + case "$path" in + README.*.md) + error \ + "$path" \ + "translated project entry docs must live under docs/project/" \ + "move it to docs/project/$(basename "$path")" + ;; + CONTRIBUTING.*.md) + error \ + "$path" \ + "translated project entry docs must live under docs/project/" \ + "move it to docs/project/$(basename "$path")" + ;; + esac + + if [[ "$path" =~ (^|/)README_[A-Za-z0-9-]+\.md$ ]]; then + error \ + "$path" \ + "legacy README translation names are not allowed" \ + "rename it to use README..md, for example $(suggest_noncanonical_translation_name "$path")" + fi + + if is_noncanonical_translation_name "$path"; then + error \ + "$path" \ + "translation files must use lowercase ..md suffixes and no underscore variants" \ + "rename it to $(suggest_noncanonical_translation_name "$path")" + fi + + if is_root_docs_language_bucket "$path"; then + error \ + "$path" \ + "language bucket directories under docs/ are not allowed" \ + "move it to $(suggest_docs_language_bucket_target "$path")" + fi + + if is_noncanonical_locale_bucket "$path"; then + error \ + "$path" \ + "translations must live beside the English source, not under locale-named subdirectories" \ + "move it to $(suggest_nested_locale_bucket_target "$path")" + fi + + if [[ "$path" =~ ^docs/[^/]+\.md$ && "$path" != "docs/README.md" ]]; then + error \ + "$path" \ + "top-level docs Markdown files must move into a typed docs/ subdirectory" \ + "move it into one of docs/project/, docs/guides/, docs/reference/, docs/operations/, docs/security/, docs/architecture/, docs/channels/, docs/design/, or docs/migration/" + fi + + if is_translation_file "$path"; then + locale="${BASH_REMATCH[2]}${BASH_REMATCH[3]}" + + if [[ "$path" == docs/design/* ]]; then + continue + fi + + base="$(translation_base "$path" "$locale")" + if [[ ! -f "$base" ]]; then + error \ + "$path" \ + "missing English source document '$base'" \ + "add the English source document at '$base' or move this translation beside the correct English source" + fi + fi +done < <(git ls-files --cached --others --exclude-standard -- '*.md') + +if [[ "$failures" -ne 0 ]]; then + echo "docs lint: failed" >&2 + exit 1 +fi + +echo "docs lint: OK"