Skip to content

Developer Documentation Design

Issue: #8 Date: 2026-05-13

Goal

Create developer-facing documentation with a getting-started guide, use case examples, code examples in cURL/Python/JS, and an API reference. All code examples in the docs must be tested in CI so they never drift from the implementation.

Approach

MkDocs site with pymdownx.snippets for tested code inclusion. Example code lives in standalone runnable files, tests import and execute them, and MkDocs pulls snippets from those same files into the docs pages. No hand-written code blocks for API usage in the docs.

Architecture

Three layers:

  1. examples/ — Standalone, runnable code files (Python, JS, shell scripts). Source of truth for all code shown in docs.
  2. tests/test_examples.py — Imports and executes the example files against the test API. Runs in CI alongside existing tests.
  3. docs/ — MkDocs markdown files that pull snippets from examples/ using --8<-- syntax.

Dependencies: mkdocs, mkdocs-material (theme — includes pymdownx extensions).

Docs Site Structure

Home (index.md)

Hero tagline, one-paragraph concept ("shortlinks as event triggers"), three use cases (packaging QR with SKU data, campaign attribution, webhook triggers), and a "Get Started" link.

Quickstart (quickstart.md)

Five-step walkthrough:

  1. Get an API key
  2. Create a shortlink with data
  3. Click the link
  4. See the webhook fire
  5. Generate a QR code

Each step shows cURL pulled from examples/create_link.sh.

Code Examples (examples.md)

Same operations in Python (requests) and JavaScript (fetch). Webhook receiver examples in FastAPI and Express.js with HMAC signature verification. All pulled from examples/.

API Reference (api-reference.md)

Table of all endpoints with method, path, auth requirement, and description. Links to live Swagger UI at https://usnp.me/docs for interactive exploration. Documents webhook payload shape, X-Webhook-Signature header, and X-Usage response headers.

Rate Limits & Quotas (rate-limits.md)

Tier table (free/pro) with rate limits and monthly quotas. Links to GET /usage endpoint.

Example Files

File Contents
examples/create_link.sh cURL: create link, create link with data+webhooks, generate QR code
examples/create_link.py Python (requests): create link, create link with data+webhooks
examples/create_link.js JavaScript (fetch): create link, create link with data+webhooks
examples/webhook_receiver.py FastAPI receiver: verify HMAC signature, parse payload
examples/webhook_receiver.js Express.js receiver: verify HMAC signature, parse payload

Testing Strategy

A single tests/test_examples.py file:

  • Python examples: Import and execute against the mock test API. Assert correct status codes and response shapes.
  • cURL examples: Parse the shell commands to extract URLs, methods, headers, and bodies. Replay them as equivalent test_client requests. Verify the documented endpoints and payloads are correct.
  • JS examples: Validate fetch URLs, method, headers, and body JSON are syntactically correct and match the API contract. Does not run Node — verifies request shape only.
  • Webhook receivers: Call the receiver functions directly with a test payload and HMAC signature. Assert they accept valid signatures and reject invalid ones.

Every code example shown in the docs is exercised by pytest. If an endpoint or payload shape changes, the example tests break.

README

Replace the current README.md with a short landing page:

  • Tagline and one-paragraph description
  • Badge linking to the docs site
  • "Get Started" link to the quickstart page
  • Link to Swagger UI
  • Brief "Development" section (local dev commands, run tests)

No API reference or code examples in the README.

Deployment

  • mkdocs gh-deploy pushes to GitHub Pages on every push to main (add step to existing GitHub Actions workflow).
  • Initial URL: granteagon.github.io/usnap.me (custom domain later).
  • Theme: mkdocs-material with dark mode toggle.
  • Extensions: pymdownx.snippets, pymdownx.highlight, pymdownx.superfences.

Out of Scope

  • Custom domain configuration (can do later)
  • Contributing guide
  • Changelog
  • Self-hosting docs
  • Docs versioning