docs/ Guidelines -- Verilator documentation (*.rst)

When to check: before editing anything under docs/. Read the repository-root AGENTS.md first for process and cross-cutting rules.

Writing rules

Rewrap paragraphs after editing -- keep consistent line length in *.rst files.
Document only stable, implemented features -- never planned or in-development capabilities; prevents user confusion and support burden.
Explain WHAT and WHEN, not HOW -- conceptual purpose and practical use cases over implementation mechanics; describe behavior ("optimized as pure", not "treated as pure") and clarify ambiguous referents ("in the internals of Verilator").
Keep terminology consistent -- one term per concept; update docs when renaming code constructs; spell out full terms, avoiding abbreviations like "sim"/"sims".
Use "how many" for countable nouns (threads, tasks, workers) and "how much" for uncountable quantities.
Mark internal or experimental features "for internal use only" -- prevents user dependence and forced deprecation cycles later.
Use specific IEEE references: IEEE {number}-{year} plus the section (e.g. Annex I) -- a vague "IEEE spec requires" is unverifiable.
Document all flags with descriptions, not just syntax.

Use the :vlopt: role for Verilator option references -- makes cross-references clickable and consistent.
Escape angle brackets (\<, \>) in link targets -- prevents broken links to command-line options.
Generate documentation examples with test.extract from test_regress test files -- examples stay synced with actually tested behavior.

Never edit docs/CONTRIBUTORS -- only humans may, after reading and agreeing to its statement; remind the user instead.