Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (51 loc) · 3.41 KB

AGENTS.md

File metadata and controls

75 lines (51 loc) · 3.41 KB
Raw

AGENTS.md

This file provides guidance to AI coding agents when working with this repository.

Project Overview

OTDocs is the documentation website for OpenTrafficCam, an open-source workflow for video-based traffic analysis. The site is built with MkDocs using the Material theme.

Language: The main site pages (landing page, pricing, team) are in German (language: de in mkdocs.yml). The documentation section under docs/ (OTCamera, OTVision, OTAnalytics, OTLabels, contribute) is written in English. Repository tooling (this file, README, configs, workflows) is also in English.

Commands

Setup

sh ./install_dev.sh

Creates a Python venv in ./venv and installs dependencies from requirements.txt.

Local Development Server

sh ./start_local_server.sh

Ensures venv is up to date, then runs mkdocs serve at http://127.0.0.1:8000 with auto-reload.

Build

./venv/bin/python -m mkdocs build

Generates static HTML in /site.

Architecture

  • docs/ — Markdown source files organized by module: OTCamera/, OTVision/, OTAnalytics/, OTLabels/, plus overview/, contribute/
  • mkdocs.yml — Central config: navigation (nav:), theme, plugins, markdown extensions. New pages must be added to nav:.
  • overrides/ — Custom Material theme templates (HTML). Watched by MkDocs for auto-reload.
  • docs/stylesheets/ — Custom CSS (colors, fonts, KaTeX, admonitions)
  • docs/assets/ — Images (img/), videos (video/), JavaScript (js/ for KaTeX), fonts, icons
  • site/ — Build output (gitignored)
  • gh-pages branch — Auto-generated by deployment; never edit directly

Linting

PRs run GitHub super-linter slim v7 (only on changed files) plus a test build (mkdocs build). The following linters are active:

  • markdownlint — Config: .markdownlint.yaml. Key rules: line length 200 chars (headings: 80), unordered list indent 2 spaces, images must have alt text (MD045), inline HTML restricted to <figure> and <figcaption> only (MD033), files must end with single newline (MD047).
  • yamllint — Config: .github/linters/.yaml-lint.yml. Line length disabled, key ordering disabled, document-start is warning-only.
  • HTMLHint — Config: .github/linters/.htmlhintrc. Only custom rule: doctype-first: false.
  • stylelint — Config: .github/linters/.stylelintrc.json. Extends stylelint-config-standard, disables custom-property-pattern and selector-class-pattern.

Explicitly disabled: JavaScript (ES + Standard), Python (pylint, mypy, black), JSCPD, Go Releaser.

Content Guidelines

  • Navigation is defined in mkdocs.yml under nav:. Adding a new page requires an entry there.
  • Markdown extensions available: admonitions, mermaid diagrams, KaTeX math ($...$), tabbed content, task lists, footnotes, keys, snippets, emoji (twemoji), tables, attribute lists, inline HTML (limited).
  • All images must have alt text (enforced by markdownlint MD045).

Git Workflow

  • Work on feature branches, PR to master.
  • Never commit to master or gh-pages directly.
  • Merges to master trigger automatic deployment via GitHub Actions (mkdocs gh-deploy --force).
  • PRs run super-linter and a test build (see Linting section above).
  • Dependabot checks for weekly updates to pip packages and GitHub Actions.
  • Never merge pull requests. Merging is always done by a human reviewer.