Skip to content

Contributing

This documentation site is built with MkDocs Material and deployed automatically via GitHub Actions.

Quick Start

# Clone the repo
git clone git@github.com:thanakijwanavit/villa-ecommerce-docs.git
cd villa-ecommerce-docs

# Install dependencies
pip install -r requirements.txt

# Start local preview server
mkdocs serve

Open http://localhost:8000 to see the docs locally. Changes are live-reloaded.

Making Changes

  1. Create a branch: git checkout -b docs/your-change
  2. Edit markdown files in docs/
  3. Preview locally with mkdocs serve
  4. Commit and push: git push -u origin docs/your-change
  5. Create a pull request

On merge to main, GitHub Actions automatically builds and deploys to docs.villaecommerce.com.

File Structure

docs/
  index.md              # Home page
  api-reference.md      # API endpoint documentation
  architecture.md       # System architecture diagrams
  business-logic.md     # Calculation pipeline and formulas
  data-models.md        # Data model class definitions
  service-interfaces.md # Protocol interfaces and adapters
  test-inventory.md     # Test file catalog
  test-ui.md            # Interactive test tool
  known-behaviors.md    # Backward-compatible quirks
  migration-guide.md    # Import mapping from old code
  cross-account-setup.md # AWS cross-account configuration
  coupon-rewrite-spec.md # Future coupon work specification
  contributing.md       # This file
  assets/               # Diagrams, images, downloadable files

Style Guide

  • No emojis in documentation text
  • Use code blocks for formulas, command examples, and code snippets
  • Use tables for structured data (fields, types, defaults)
  • Use Mermaid for diagrams (rendered natively by MkDocs Material)
  • Use admonitions for warnings, notes, and tips:
!!! warning
    This behavior is preserved for backward compatibility.

!!! note
    The core module has zero AWS imports.
  • Keep each page focused on one topic
  • Cross-reference other pages with relative links: [Architecture](architecture.md)

Adding a New Page

  1. Create a new .md file in docs/
  2. Add it to the nav section in mkdocs.yml
  3. Preview with mkdocs serve
  4. Commit and create a PR