mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-19 12:50:11 -05:00
Dries Peeters
7534e8abe7
Describe how GET /api/openapi.json sets info.version via get_version_from_setup() (setup.py at runtime, with TIMETRACKER_VERSION or APP_VERSION overrides and Flask APP_VERSION fallback), and point contributors to the same rules in version management and project structure docs. Update the documentation audit entry for the former hardcoded OpenAPI version gap, document tests/test_api_route_contract.py and the refined test_api_v1 isolation guidance in the testing strategy, add a quick-reference pytest invocation for the contract suite, and note info.version in the API consistency audit next to the OpenAPI references.
74 lines
5.0 KiB
Markdown
74 lines
5.0 KiB
Markdown
# Documentation Audit Summary
|
|
|
|
This audit summarizes the state of TimeTracker documentation as of the audit date. Use it to find accurate sources, fix outdated content, and fill gaps.
|
|
|
|
---
|
|
|
|
## Accurate (keep; minimal edits only)
|
|
|
|
| Doc | Notes |
|
|
|-----|--------|
|
|
| **README.md** | Tech stack, quick start (Docker HTTPS/HTTP/SQLite), features, doc links correct. Version: states "defined in setup.py"; avoid hardcoding version examples in What's New. |
|
|
| **INSTALLATION.md** | Matches actual flow; points to GETTING_STARTED and DOCKER_COMPOSE_SETUP. |
|
|
| **DEVELOPMENT.md** | Venv + `flask run`, `docker-compose.local-test.yml`, folder structure, test commands align with repo. |
|
|
| **ARCHITECTURE.md** | Module table, data flow, API structure match app/ (blueprint_registry, routes, services, repositories, models). |
|
|
| **API.md** (root), **docs/api/REST_API.md** | Accurate overview and auth; REST_API is full reference. |
|
|
| **docs/development/SERVICE_LAYER_AND_BASE_CRUD.md** | Accurately describes service/repository pattern and BaseCRUDService. |
|
|
| **docs/development/LOCAL_TESTING_WITH_SQLITE.md** | Correct for docker-compose.local-test.yml and scripts. |
|
|
| **docs/TESTING_QUICK_REFERENCE.md**, **docs/TESTING_COVERAGE_GUIDE.md** | Align with Makefile targets and pytest markers. |
|
|
| **docs/UI_GUIDELINES.md**, **docs/FRONTEND.md** | Match templates (base.html, components/ui.html) and Tailwind. |
|
|
| **docs/GETTING_STARTED.md** | Correct: default compose → https://localhost; documents example compose for http://localhost:8080. |
|
|
| **requirements-test.txt** | Exists; referenced by Makefile and CI. |
|
|
|
|
---
|
|
|
|
## Outdated
|
|
|
|
| Item | Location | Fix |
|
|
|------|----------|-----|
|
|
| Version numbers | README "What's New" / "Current version" | Point to setup.py + CHANGELOG only; remove or generalize hardcoded v4.14.0, v4.6.0. |
|
|
| Hardcoded version | docs/development/PROJECT_STRUCTURE.md | **Resolved:** OpenAPI `info.version` uses `get_version_from_setup()` + env overrides; see PROJECT_STRUCTURE versioning section. |
|
|
| Hardcoded version | docs/FEATURES_COMPLETE.md | Remove "Version: 4.20.6" or replace with "See setup.py". |
|
|
| Docker access URL | docs/development/CONTRIBUTING.md | Default `docker-compose up --build` → https://localhost. For http://localhost:8080 use docker-compose.example.yml or docker-compose.local-test.yml. |
|
|
| Compose role | docs/development/PROJECT_STRUCTURE.md | Describe docker-compose.yml as "Default stack (HTTPS via nginx)"; add docker-compose.example.yml (HTTP 8080) and docker-compose.local-test.yml (SQLite). |
|
|
| Refactored modules | docs/ARCHITECTURE_AUDIT.md | Note that timer_refactored/projects_refactored/invoices_refactored are historical (merged or removed). |
|
|
| Deployment guide label | docs/guides/DEPLOYMENT_GUIDE.md | Content is feature checklist, not "how to deploy". Add note at top pointing to DOCKER_COMPOSE_SETUP and DOCKER_PUBLIC_SETUP. |
|
|
|
|
---
|
|
|
|
## Missing
|
|
|
|
| Gap | Resolution |
|
|
|-----|------------|
|
|
| Single contributor onboarding doc | **CONTRIBUTOR_GUIDE.md** — Architecture, local dev, testing, how to add route/service/repository/template, versioning. |
|
|
| Versioning for contributors | Short "For contributors" note: app version in setup.py only; desktop/mobile have own config; link BUILD.md and VERSION_MANAGEMENT. |
|
|
| Step-by-step "add route/service/repository/template" | Include in CONTRIBUTOR_GUIDE with concrete steps (files, blueprint_registry, tests). |
|
|
|
|
---
|
|
|
|
## Duplicated or Overlapping
|
|
|
|
| Area | Notes |
|
|
|------|--------|
|
|
| **Installation** | README Quick Start, INSTALLATION.md, GETTING_STARTED.md, DOCKER_COMPOSE_SETUP all cover install. Keep overlap; add one-line pointers (e.g. "For step-by-step see INSTALLATION.md", "For all env vars see DOCKER_COMPOSE_SETUP"). |
|
|
| **Contributing** | Root CONTRIBUTING.md points to docs/development/CONTRIBUTING.md; fix Docker URL in full CONTRIBUTING. |
|
|
| **Deployment** | README, INSTALLATION, DOCKER_COMPOSE_SETUP, DOCKER_PUBLIC_SETUP, guides/DEPLOYMENT_GUIDE. Clarify DEPLOYMENT_GUIDE as feature checklist; "how to deploy" = DOCKER_COMPOSE_SETUP / DOCKER_PUBLIC_SETUP. |
|
|
|
|
---
|
|
|
|
## Contradictions
|
|
|
|
| Issue | Resolution |
|
|
|-------|------------|
|
|
| **Docker URL** | CONTRIBUTING (full) said http://localhost:8080 after default `docker-compose up --build`. Default compose serves **HTTPS** (https://localhost). Fix: document default = https://localhost; for 8080 use docker-compose.example.yml or docker-compose.local-test.yml. |
|
|
| **Compose purpose** | PROJECT_STRUCTURE said "Local development compose" for docker-compose.yml; README uses it for quick start and production. Unify: default = full stack HTTPS; development options = example (HTTP) or local-test (SQLite). |
|
|
|
|
---
|
|
|
|
## File reference
|
|
|
|
- **Audit doc**: this file — `docs/DOCS_AUDIT.md`
|
|
- **Updates**: README.md, docs/development/CONTRIBUTING.md, docs/development/PROJECT_STRUCTURE.md, docs/FEATURES_COMPLETE.md, docs/ARCHITECTURE_AUDIT.md, docs/README.md, docs/guides/DEPLOYMENT_GUIDE.md
|
|
- **New**: docs/development/CONTRIBUTOR_GUIDE.md
|
|
- **Cross-links**: CONTRIBUTING.md (root), docs/README.md, DEVELOPMENT.md
|