name: document description: Documentation style guide and rules for creating documentation

Document Rules

Documentation style varies by type. Follow these principles for consistency.

Specification Documents (docs/specification/)

Purpose: Formal mathematical reference for constitutions, geometries, and core concepts.

Rules:

• Use LaTeX math ($$ for display, $ for inline) extensively
• Define all variables after formulas
• Prefer math over code examples
• Structure: Definition → State Variables → Formulations → Energy Functions
• Use numbered sections: ## #12 Hookean Spring
• Reference academic papers when applicable
• Include parameter ranges: "$100MPa \le \kappa \le 100GPa$"
• Explain notation: "where $|\cdot|_F$ is the Frobenius norm"
• Cross-reference: [link text](./file.md)
• Include diagrams (SVG): ![Description](./media/figure.svg)

Example:

# Hookean Spring

**Hookean Spring** is a constitutive model for simulating linear elastic springs.

## #12 Hookean Spring

$$
E = \frac{\kappa}{2} \epsilon^2 = \frac{\kappa}{2} \left(\frac{L - L_0}{L_0}\right)^2
$$

where:
- $\kappa$ is the spring constant
- $L_0$ is the rest length

Tutorial Documents (docs/tutorial/)

Purpose: User-friendly guides with code examples.

Rules:

• Always provide both C++ and Python using tabs:

  === "C++"
      \`\`\`cpp
      // code
      \`\`\`
  === "Python"
      \`\`\`python
      # code
      \`\`\`
  

• Include complete, runnable examples with imports
• Start high-level, progress to details
• Use diagrams: ![description](./media/file.svg)
• Include step-by-step workflows
• Use tables for structured data

Example:

=== "C++"
    \`\`\`cpp
    using namespace uipc::core;
    Scene scene;
    \`\`\`
=== "Python"
    \`\`\`python
    from uipc.core import *
    scene = Scene()
    \`\`\`

Reference Documents (docs/specification/*_uid.md)

Purpose: Technical reference for identifiers and ranges.

Rules:

• Define identifier ranges clearly
• Distinguish official vs. user-defined ranges
• List all official identifiers
• Cross-reference to detailed specs

Example:

# Constitution UID

64-bit unsigned integer. Official range: $[0, 2^{32}-1]$. User-defined: $[2^{32}, 2^{64}-1]$.

Build/Install Documents (docs/build_install/)

Purpose: Step-by-step build instructions.

Rules:

• Use prerequisites table with versions and links
• Number steps clearly
• Include verification commands
• Use shell tags: shell, bash, powershell
• Show copy-pasteable commands

Example:

| Name | Version | Usage | Import |
|------|---------|-------|--------|
| [CMake](https://cmake.org/) | >=3.26 | build system | system install |

\`\`\`shell
git clone https://github.com/microsoft/vcpkg.git
\`\`\`

General Rules

• Math: $$ for display, $ for inline. Define variables after formulas. Use bold for vectors: $\mathbf{x}$
• Code: Appropriate language tags. Complete, runnable examples. C++/Python tabs in tutorials
• Links: Relative paths [text](./file.md). Link to related docs and external resources
• Media: Store in media/ subdirectories. Use SVG. Reference: ![Description](./media/file.svg)
• Tables: Markdown tables with headers for structured data
• Headers: # title, ## sections, ### subsections

Checklist

• Formulas use LaTeX, variables defined
• Code examples complete and runnable
• Cross-references use relative paths
• Images exist and are referenced
• Tables formatted correctly
• Document type principles followed
• No ambiguity in technical descriptions