Development

Run Wenmode’s local test, lint, type-check, benchmark, and documentation build tasks.

Wenmode uses uv for local development tasks.

Install dependencies on demand by running the task-specific uv run --group ... commands below from the repository root.

Run the test suite:

uv run --group test pytest -q

Run linting and type checks:

uv run --group lint ruff check .
uv run --group lint mypy

Build the documentation:

Documentation tooling currently requires Python 3.11+.

uv run --group docs sphinx-build -b html docs docs/_build/html

Build with warnings treated as errors when preparing documentation changes:

uv run --group docs sphinx-build -b html docs /tmp/wenmode-docs-html -W --keep-going

Check external documentation links:

uv run --group docs sphinx-build -b linkcheck docs /tmp/wenmode-docs-linkcheck

Documentation workflow

When changing documented behavior, update the smallest set of docs that matches the user-facing surface:

  • usage.md for high-level API behavior.

  • presets.md for ready-made rule sets.

  • security.md for renderer escaping, URL handling, and raw HTML behavior.

  • rule-matrix.md for rule options, preset membership, and streaming support.

  • compliance.md for CommonMark/GFM fixture coverage and known differences.

  • changelog.md for user-facing changes, upgrade notes, and compatibility updates.

  • benchmarks.md for benchmark methodology, versions, and results.

  • troubleshooting.md for common integration failures and fixes.

  • recipes.md for copyable integration patterns.

  • integrations.md for end-to-end application pipelines.

  • migration/*.md for parser-to-Wenmode migration guides.

  • rules.md and custom-rules.md for parser extension behavior.

  • references/*.md for rule syntax, AST shape, and default HTML output.

  • api/*.rst for generated Python API organization.

Runnable Python examples in guide pages are exercised by tests/test_docs_examples.py. Keep examples self-contained when possible. If a snippet is intentionally partial, make sure the test skip rules identify it explicitly rather than silently ignoring a whole page.

Rule change checklist

When adding or changing a public rule:

  • Add parser and renderer tests for recognized syntax and fallback behavior.

  • Update the relevant preset documentation if the rule is enabled there.

  • Update the reference page with syntax, AST shape, and HTML output.

  • Add or update a recipe when the rule supports a common integration task.

  • Run the strict docs build and docs example tests before release.