sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-02-27 18:22:41 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs: overhaul documentation and add four new pages

Browse Source 
- Add mining-workflow.md: end-to-end sentence mining guide
- Add anki-integration.md: AnkiConnect setup, field mapping, media generation, field grouping
- Add mpv-plugin.md: chord keybindings, subminer.conf options, script messages
- Add troubleshooting.md: common issues and solutions by category
- Rewrite architecture.md to reflect current ~1,400-line main.ts and ~35 services
- Expand development.md from ~25 lines to full dev guide
- Fix URLs to ksyasuda/SubMiner, version to v0.1.0, AppImage naming
- Update VitePress sidebar with three-group layout (Getting Started, Reference, Development)
- Update navigation in index.md, README.md, docs/README.md
- Remove obsolete planning artifacts (plan.md, investigation.md, comparison.md, composability.md, refactor-main-checklist.md)
This commit is contained in:
Kyle Yasuda
2026-02-10 23:25:14 -08:00
parent 9f0f8a2ce9
commit 781e6dd4fa
16 changed files with 1045 additions and 1295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
docs/development.md
View File

@@ -1,20 +1,99 @@
# Contributor Note
# Development
To add or change a config option, update `src/config/definitions.ts` first. Defaults, runtime-option metadata, and generated `config.example.jsonc` are derived from this centralized source.
## Prerequisites
## Architecture
- [Node.js](https://nodejs.org/) (LTS)
- [pnpm](https://pnpm.io/)
- [Bun](https://bun.sh) (for the `subminer` wrapper script)
The current runtime design, composition model, and extension guidelines are documented in [`architecture.md`](/architecture).
## Setup
Contributor guidance:
```bash
git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
make deps
# or manually:
pnpm install
pnpm -C vendor/texthooker-ui install
```
## Building
```bash
# TypeScript compile (fast, for development)
pnpm run build
# Full platform build (includes texthooker-ui + AppImage/DMG)
make build
# Platform-specific builds
make build-linux # Linux AppImage
make build-macos # macOS DMG + ZIP (signed)
make build-macos-unsigned # macOS DMG + ZIP (unsigned)
```
## Running Locally
```bash
pnpm run dev # builds + launches with --start --dev flags
```
## Testing
```bash
pnpm run test:config # Config schema and validation tests
pnpm run test:core # Core service tests (~67 tests)
pnpm run test:subtitle # Subtitle pipeline tests
```
All test commands build first, then run via Node's built-in test runner (`node --test`).
## Config Generation
```bash
# Generate default config to ~/.config/SubMiner/config.jsonc
make generate-config
# Regenerate the repo's config.example.jsonc from centralized defaults
make generate-example-config
# or: pnpm run generate:config-example
```
## Documentation Site
The docs use [VitePress](https://vitepress.dev/):
```bash
make docs-dev # Dev server at http://localhost:5173
make docs # Build static output
make docs-preview # Preview built site at http://localhost:4173
```
## Makefile Reference
Run `make help` for a full list of targets. Key ones:
| Target | Description |
| --- | --- |
| `make build` | Build platform package for detected OS |
| `make install` | Install platform artifacts (wrapper, theme, AppImage/app bundle) |
| `make install-plugin` | Install mpv Lua plugin and config |
| `make deps` | Install JS dependencies (root + texthooker-ui) |
| `make generate-config` | Generate default config from centralized registry |
| `make docs-dev` | Run VitePress dev server |
## Contributor Notes
- To add or change a config option, update `src/config/definitions.ts` first. Defaults, runtime-option metadata, and generated `config.example.jsonc` are derived from this centralized source.
- Overlay window/visibility state is owned by `src/core/services/overlay-manager-service.ts`.
- Prefer direct inline deps objects in `main.ts` for simple pass-through wiring.
- Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
- See [Architecture](/architecture) for the composition model and extension rules.
## Environment Variables
| Variable | Description |
| ------------------------ | ---------------------------------------------- |
| Variable | Description |
| --- | --- |
| `SUBMINER_APPIMAGE_PATH` | Override AppImage location for subminer script |
| `SUBMINER_YT_SUBGEN_MODE` | Override `youtubeSubgen.mode` for launcher |
| `SUBMINER_WHISPER_BIN` | Override `youtubeSubgen.whisperBin` for launcher |