Documentation & Code Style Guide

Use this guide when contributing to the Tick Backtest Research Stack or updating the documentation site.

Code Style

• Follow the existing formatting conventions (PEP 8, type hints, descriptive logging).
• Do not remove or override user-provided configurations; prefer additive changes.
• Ensure new modules include focused unit tests; integration tests should remain deterministic.

Documentation Workflow

1. Draft updates in Markdown under docs/.
2. Run mkdocs serve locally to preview changes.
3. Place contributor-/maintainer-focused material under docs/dev/ to keep the main guides user-friendly.
4. Keep installed-package usage primary on user-facing pages; move checkout-only details into clearly labeled contributor sections or docs/dev/.
5. Keep user-facing pages concise and task-oriented; link to deeper references when needed.

Tooling

• Install doc dependencies via:

  pip install -r requirements-docs.txt
  

• Build the static site with:

  mkdocs build --strict
  

Content Guidelines

• Use admonitions (!!! note) for important callouts; keep tables for schema references.
• Embed diagrams using Mermaid when possible; store exported assets in docs/_static/.
• Cross-link between pages to avoid duplication (e.g., configs.md ↔ analysis.md).

Release Checklist

• Update mkdocs.yml navigation if new pages are added.
• Regenerate screenshots or sample manifests when output format changes.
• Verify Quickstart and contributor setup instructions against the latest README.md, requirements.txt, and actual package workflow.
• Summarise documentation changes in the project changelog or release notes so external users can track updates.

Maintain this guide as your checklist for consistent documentation quality.