appwrite / appwrite/sdk-generator

📚 Documentation: Add Vale linting for all generated docs and examples

Open
#1,822 1 comment 0 reactions 1 assignee Claimed by @kekubhai View on GitHub
Dominant language
Twig
Stars
325
Forks
212
Avg merge
7h 36m
Merged PRs (30d)
91

Description

## Description

Add Vale validation for every Markdown file produced by the SDK generator, including SDK READMEs, generated documentation, and Markdown examples.

Markdown is generated across many language templates, so style issues can be repeated in every published SDK. The generated output in `examples//` is the ground truth and should be checked after generation rather than linting Twig templates alone.

## Proposed changes

- Add a repository-wide Vale configuration and shared vocabulary/style rules for generated Markdown.
- Update Markdown templates so all generated READMEs, docs, and examples pass Vale.
- Add a script that generates the supported SDK outputs and runs Vale against every generated `*.md` file under `examples/`.
- Run that check in CI when generator code, Markdown templates, or Vale configuration changes.
- Document the local command contributors should run after editing Markdown-producing templates.

## Acceptance criteria

- All Markdown files emitted by every supported generator target are included; the check is not limited to top-level READMEs.
- Generated documentation and Markdown examples pass Vale without errors.
- Necessary technical terms and product names are captured in a checked-in vocabulary instead of being suppressed ad hoc.
- Intentional exceptions, such as verbatim third-party specification text, are narrowly scoped and documented.
- CI fails when a template change introduces a Vale error in generated Markdown.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.