40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
Core Python code is in `docutranslate/`.
|
|
- `docutranslate/workflow/`: file-type workflows (`*_workflow.py`) that orchestrate conversion, translation, and export.
|
|
- `docutranslate/converter/`, `docutranslate/translator/`, `docutranslate/exporter/`: pipeline stages.
|
|
- `docutranslate/app.py`: FastAPI/Web UI backend entrypoint.
|
|
- `docutranslate/cli.py`: CLI entry (`docutranslate` command).
|
|
- `docutranslate/static/` and `docutranslate/template/`: bundled frontend/static assets.
|
|
- Packaging/build files live at root: `pyproject.toml`, `Dockerfile`, `*.spec`, `.github/workflows/`.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `uv sync`: install project dependencies from `pyproject.toml`/`uv.lock`.
|
|
- `uv run docutranslate -i`: start local Web UI + API (default `127.0.0.1:8010`).
|
|
- `uv run docutranslate -i -p 8011 --cors`: run on a custom port with CORS enabled.
|
|
- `docker run -d -p 8010:8010 xunbu/docutranslate:latest`: run the published container locally.
|
|
- `uv pip install pyinstaller && uv run pyinstaller lite.spec --noconfirm --clean -y`: build a lightweight desktop package (see also `full.spec`, `lite_mac.spec`).
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Follow Python 3.11+ conventions and PEP 8: 4-space indentation, clear type-oriented config classes, small focused functions.
|
|
- Use `snake_case` for modules/functions/variables and `PascalCase` for classes.
|
|
- Keep workflow naming consistent: `xxx_workflow.py`, matching config and workflow class names.
|
|
- Prefer explicit, composable configs over hard-coded provider values.
|
|
|
|
## Testing Guidelines
|
|
There is currently no first-party `tests/` suite or enforced coverage gate in this repository.
|
|
- For behavior changes, run a manual smoke test: start `docutranslate -i`, open `/docs`, and execute at least one translation path you touched.
|
|
- If you add automated tests, place them under `tests/` with `test_*.py` names and keep fixtures small and file-type specific.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
Recent history favors short, imperative commit subjects (Chinese or English), for example: `Fix Gemini provider tag`, `Add regex dependency`, `Add Vietnamese`.
|
|
- Keep subject lines concise and action-focused.
|
|
- In PRs, include: what changed, why, how you validated it, and UI screenshots when `docutranslate/static/` or interface behavior changes.
|
|
- Link related issues and note any new env vars/API provider requirements.
|
|
|
|
## Security & Configuration Tips
|
|
- Never commit real API keys or tokens.
|
|
- Keep provider credentials in environment variables or local untracked config.
|
|
- For LAN exposure, use `--host 0.0.0.0` intentionally and restrict network access as needed.
|