mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-17 05:40:42 -07:00
docs: refresh contributor docs and drop root requirements.txt
CONTRIBUTING.md caught up with reality: ruff not Black, Python 3.12, sh.voicebox.app, the routes/services/backends layout, the actual pytest + CI story, and a working autoupdater link. SECURITY.md now says 0.5.x and describes what CI actually enforces. The root requirements.txt was vestigial (unpinned, included torchvision, referenced by nothing) — deleted, with two stale doc references repointed at backend/requirements.txt. backend/pyproject.toml is now covered by bumpversion; its version was stuck at 0.2.3 and is synced to 0.5.0.
This commit is contained in:
@@ -258,20 +258,8 @@ When adding new API endpoints:
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Regenerate Client">
|
||||
```bash
|
||||
just generate-api
|
||||
```
|
||||
|
||||
This updates the TypeScript client with type-safe bindings.
|
||||
</Step>
|
||||
|
||||
<Step title="Update Docs">
|
||||
The API documentation is automatically generated from the OpenAPI schema. Ensure your endpoint has proper docstrings and type hints, then regenerate the docs:
|
||||
|
||||
```bash
|
||||
just generate-api
|
||||
```
|
||||
<Step title="Update the Frontend Client">
|
||||
The TypeScript client is hand-written. Add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts`. The backend's live schema at `http://localhost:17493/docs` is the reference.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ Ensure you have these installed:
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
</Card>
|
||||
<Card title="Python 3.11+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
|
||||
<Card title="Python 3.12+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
|
||||
[Download Python](https://python.org)
|
||||
```bash
|
||||
python --version
|
||||
@@ -111,7 +111,6 @@ Run `just --list` to see all available commands. Highlights:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `just generate-api` | Generate TypeScript API client from the backend's OpenAPI schema |
|
||||
| `just docs` | Open `http://localhost:17493/docs` in your browser |
|
||||
| `just logs` | Tail backend logs |
|
||||
| `just clean` | Remove build artifacts |
|
||||
@@ -184,15 +183,9 @@ See [Model Management](/developer/model-management) for the full list.
|
||||
First-time usage will be slower due to model downloads, but subsequent runs will use cached models.
|
||||
</Callout>
|
||||
|
||||
## Generate OpenAPI Client
|
||||
## Frontend API Client
|
||||
|
||||
After starting the backend server, generate the TypeScript API client:
|
||||
|
||||
```bash
|
||||
just generate-api
|
||||
```
|
||||
|
||||
This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`.
|
||||
The TypeScript API client is hand-written: request/response types live in `app/src/lib/api/types.ts` and the fetch wrapper in `app/src/lib/api/client.ts`. When you add or change a backend endpoint, update both to match. The backend's live schema at `http://localhost:17493/docs` is the reference.
|
||||
|
||||
## Manual Setup (Advanced)
|
||||
|
||||
@@ -277,9 +270,9 @@ bun run tauri dev
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Backend won't start">
|
||||
- Check Python version (must be 3.11+)
|
||||
- Check Python version (must be 3.12+)
|
||||
- Ensure virtual environment is activated: `source backend/venv/bin/activate`
|
||||
- Verify all dependencies are installed: `pip install -r requirements.txt`
|
||||
- Verify all dependencies are installed: `pip install -r backend/requirements.txt`
|
||||
- Check if port 17493 is available
|
||||
</Accordion>
|
||||
|
||||
|
||||
@@ -355,39 +355,6 @@ cd ../..
|
||||
bun run tauri build
|
||||
```
|
||||
|
||||
### OpenAPI Client Generation Fails
|
||||
|
||||
**Symptoms:**
|
||||
- `./scripts/generate-api.sh` fails
|
||||
- "Failed to fetch schema" error
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<Steps>
|
||||
<Step title="Ensure Backend is Running">
|
||||
```bash
|
||||
curl http://localhost:17493/openapi.json
|
||||
```
|
||||
|
||||
Should return JSON. If not, start the backend.
|
||||
</Step>
|
||||
|
||||
<Step title="Check Port">
|
||||
Ensure nothing else is using port 17493
|
||||
</Step>
|
||||
|
||||
<Step title="Regenerate Manually">
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
uvicorn main:app --reload --port 17493
|
||||
|
||||
# In another terminal
|
||||
./scripts/generate-api.sh
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Database Issues
|
||||
|
||||
### "Database is locked" Error
|
||||
|
||||
Reference in New Issue
Block a user