justinzeus/scholarr
1
0
Fork 0
Code Issues 1 Pull requests 18 Projects Releases Packages Wiki Activity Actions

docs: rebuild documentation from scratch with clean IA

Browse source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Justin Visser 2026-02-27 09:39:27 +01:00
parent 6c31b331f7
commit 0c5b199b76
30 changed files with 1647 additions and 649 deletions
Download patch file Download diff file Expand all files Collapse all files

100
docs/developer/local-development.md
View file

@ -1,52 +1,100 @@
# Developer Local Development
---
title: Local Development
sidebar_position: 3
---
## Start the Dev Stack
# Local Development
## Prerequisites
- Docker and Docker Compose v2+
- Python 3.12+ (for IDE support and local linting)
- Node.js 20+ (for frontend development)
## Starting the Dev Stack
The development compose file overlays the production config with hot-reload and a separate Vite dev server:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
```
Open:
- API: `http://localhost:8000`
- Frontend dev server: `http://localhost:5173`
This starts three services:
Stop:
| Service | Port | Description |
|---------|------|-------------|
| `db` | 5432 (internal) | PostgreSQL 15 |
| `app` | 8000 | FastAPI backend with `APP_RELOAD=1` |
| `frontend` | 5173 | Vite dev server proxying API calls to `app:8000` |
### Dev-Specific Overrides
The `docker-compose.dev.yml` file applies these changes:
- **`app`**: Uses `scholarr-dev:local` image built from the `dev` stage. Mounts the project root as `/app` for hot reload. Disables `SESSION_COOKIE_SECURE` and the built frontend.
- **`frontend`**: Node 20 container running `npm install && npm run dev`. Mounts `./frontend` with a named volume for `node_modules`. Uses polling for file watching (`CHOKIDAR_USEPOLLING=1`).
## Environment Setup
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml down
cp .env.example .env
```
## Backend Validation
Set at minimum:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest tests/unit
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest -m integration
POSTGRES_PASSWORD=localdev
SESSION_SECRET_KEY=local-dev-secret-at-least-32-characters
SESSION_COOKIE_SECURE=0
```
## Frontend Validation
## Running Tests
All tests run inside containers:
```bash
cd frontend
npm install
npm run typecheck
npm run test:run
npm run build
# Run unit tests (default: excludes integration markers)
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
python -m pytest
# Run integration tests
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
python -m pytest -m integration
# Run a specific test file
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
python -m pytest tests/unit/test_fingerprints.py -v
```
## Repository Gates
See [Testing](testing.md) for markers, fixtures, and conventions.
## Linting and Type Checking
```bash
python3 scripts/check_frontend_api_contract.py
python3 scripts/check_env_contract.py
./scripts/check_no_generated_artifacts.sh
# Ruff linting
ruff check .
# Ruff formatting check
ruff format --check .
# Mypy type checking
mypy app/
```
## Docs Site (Contributor Workflow)
Ruff config is in `pyproject.toml`: target Python 3.12, line length 120, rules `E F W I UP B SIM RUF`.
Docs tooling is colocated in `docs/website/`:
## Database Migrations
Alembic migrations run automatically on startup when `MIGRATE_ON_START=1`. To run manually:
```bash
cd docs/website
npm install
npm run build
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
alembic upgrade head
```
To create a new migration:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
alembic revision --autogenerate -m "description of change"
```