Documentation style
Scope
Document interfaces and invariants owned by this repository:
language syntax and semantics
standard-library interfaces
compiler CLI and diagnostics
runtime ABI and target details needed by compiler or runtime authors
emulator, debugger, VS Code extension, and web editor
Do not document:
adapter-specific wiring or host setup
badge firmware procedures
upstream assembler usage, syntax, or examples
upstream repository contents
hardware safety advice
Link to the owning source instead.
Writing rules
Use present tense and third person.
State facts, constraints, and failure behavior.
Use one fact per sentence.
Use a table for three or more parallel facts.
Use code blocks for syntax, formats, commands, and protocol fields.
Put the most specific noun first: “The compiler rejects…”, not “It is important to note that…”.
Keep examples only when they disambiguate syntax or behavior.
Use
mustfor requirements andmayfor permission. Do not useshould.Mark unverified values as
unverifiedand cite the source, or remove them.Do not narrate implementation history, test status, or authoring process.
Prohibited prose
Delete these forms:
Form |
Action |
|---|---|
|
Delete |
|
Delete |
|
Delete |
|
Replace with a verified fact or remove |
|
Delete or state the fact |
|
State Y |
|
Rewrite as a direct statement |
|
Delete or use the passive |
|
Use |
em dash |
Use a colon, semicolon, or a new sentence |
bold emphasis |
Use a table or a heading |
Page template
# Noun phrase
One sentence defining the page.
## Scope or syntax
Facts.
## Interfaces
| Call | Returns | Behavior |
|---|---|---|
| ... | ... | ... |
## Limits
- constraint
- failure mode
Cross-references
Use Sphinx document links for internal pages:
See {doc}`../language/types`.
Use plain Markdown links for external URLs. Do not duplicate content from a linked page.
Automated checks
tools/check_docs.py rejects prohibited prose outside code blocks. Blockquotes
are excluded and may contain editorial notes.
tests/test_docs.py checks links, duplicate headings, CLI coverage, intrinsic
coverage, and public library function coverage.
Run:
python3 tools/check_docs.py
python3 -m pytest tests/test_docs.py