STYLE_GUIDE.md

Documentation & Code Comment Style Guide

This guide defines concise, practical conventions for repository documentation and Rust doc-comments used across the NOTEARS codebase.

1. Markdown files

   • Use GitHub Flavored Markdown (GFM).
   • Top-level headings: # Title for major pages, ## for sections.
   • Keep front-matter minimal: short summary first (2–4 lines), then examples.
   • Use fenced code blocks with language tags (rust, bash, ```json).

2. Rust doc-comments

   • Use /// for public API documentation and //! for module-level docs.
   • Start with a one-line summary, followed by a blank line and details.
   • Include # Examples and # Errors sections when relevant.
   • Keep examples small and copy-paste runnable where possible.

3. API Examples

   • Prefer small, idiomatic examples using library re-exports (e.g. use notears::...).
   • Mark long-running examples with no_run.

4. File organization

   • Docs live in /docs/ for long-form content; top-level READMEs present quick-starts.
   • Add cross-links to relevant guide pages (Quick Reference, Implementation Guide).

5. CHANGELOG and Release notes

   • Keep CHANGELOG.md concise: include breaking changes, new features, bug fixes.

6. Commit messages

   • Short summary (50 chars), blank line, longer description.
   • Use imperative mood: docs: add ..., fix: correct ..., chore: format ....

7. Accessibility & readability

   • Use simple language; prefer active voice and present tense.
   • Prefer bullets for steps; use code blocks for commands and examples.

8. CI & WASM docs

   • Document platform dependencies (Chromium libs) in DEPLOYMENT.md and docs/.
   • Provide a small browser usage example for notears-wasm.

This guide is intentionally short — extend topic-specific documents (e.g. CONTRIBUTING.md) when detailed workflows are required.