dtourolle
0103200fc5
The index described the manual's contents as they were before colour labels and the duplicates review, and did not say the application carries the manual or where the in-app copy of the gesture book is (Help or F1 in the grid, "?" or F1 in develop sinced9f2596and380cfda). Its conventions named two generated files; manual/index.html is a third, with its own CI check.
89 lines
4.8 KiB
Markdown
89 lines
4.8 KiB
Markdown
# Documentation
|
|
|
|
Two audiences, two folders. Most people want the first table and never the
|
|
second.
|
|
|
|
## Using DarkRoom
|
|
|
|
| | |
|
|
|---|---|
|
|
| [The manual](manual/README.md) | Every feature, pictured from the application itself — opening a library, rating, labelling and filing, duplicate originals, developing, local masks, repair, film, panoramas, export. The application carries it and opens it from Help and from Settings |
|
|
| [How it is driven](gestures.md) | Every gesture and shortcut, by screen. Generated from the code, so it cannot describe one the application does not have. The same list is the in-app help sheet: `Help` or `F1` in the grid, `?` or `F1` in develop |
|
|
|
|
The [top-level README](../README.md) says what DarkRoom is, how to get it on
|
|
each platform, and what is still missing.
|
|
|
|
## Changing DarkRoom
|
|
|
|
Everything under [`dev/`](dev/) is for someone working on the code. Start with
|
|
[CONTRIBUTING.md](../CONTRIBUTING.md), which says how to land a first change
|
|
without reading the rest.
|
|
|
|
**The register and the record.** What must be built, how it is built, and how
|
|
far along it is.
|
|
|
|
| | |
|
|
|---|---|
|
|
| [requirements.md](dev/requirements.md) | What the software must do — the numbered register, the decisions (D-numbers) and the spikes (S-numbers) |
|
|
| [architecture.md](dev/architecture.md) | How it is built — crates, the GPU pipeline, the data model, sync |
|
|
| [traceability.md](dev/traceability.md) | Generated: which requirement is claimed by which file. Never edited by hand |
|
|
| [outstanding.md](dev/outstanding.md) | What is specified and not built, and whether that is a decision or a gap |
|
|
| [technical-debt.md](dev/technical-debt.md) | Compromises taken deliberately, each with the condition that retires it |
|
|
| [code-health.md](dev/code-health.md) | What a contribution costs, per seam, measured |
|
|
|
|
**Designs, one per subsystem.** Each is the specification the code was built
|
|
to, kept current as the code moved.
|
|
|
|
| | |
|
|
|---|---|
|
|
| [catalog.md](dev/catalog.md) | The index, the library view, incremental scan, the job queue |
|
|
| [storage.md](dev/storage.md) | Storage backends: the seam a folder, a sync client and a Nextcloud account share |
|
|
| [faces.md](dev/faces.md) | Face detection, identity, clustering and the eye-state models |
|
|
| [segmentation.md](dev/segmentation.md) | How the application finds the regions a local mask snaps to |
|
|
| [mask-editing.md](dev/mask-editing.md) | Painting, erasing and combining masks |
|
|
| [spot-removal.md](dev/spot-removal.md) | Clone and heal as parameters in the edit graph |
|
|
| [panorama.md](dev/panorama.md) | Alignment, projection, the chunked composite and the border fill |
|
|
| [inference.md](dev/inference.md) | The neural runtime and model chosen per device, with the measurements |
|
|
| [display-and-extension.md](dev/display-and-extension.md) | The display contract, and why the fused pipeline is already most of a plugin format |
|
|
| [view-composition.md](dev/view-composition.md) | A controller for the display layer |
|
|
| [ui-navigation.md](dev/ui-navigation.md) | Finding things in the interface once there are many |
|
|
|
|
**Measurements.** Numbers committed so a regression is a diff rather than a
|
|
recollection.
|
|
|
|
| | |
|
|
|---|---|
|
|
| [benchmarks.md](dev/benchmarks.md) | The per-commit suite: what it covers, what it does not, how to read a failure |
|
|
| [bench-baseline.json](dev/bench-baseline.json) | The committed numbers the suite checks against |
|
|
| [frame-budget.md](dev/frame-budget.md) | What a frame costs on each device, and the decision those figures settled |
|
|
|
|
**Platforms and distribution.**
|
|
|
|
| | |
|
|
|---|---|
|
|
| [distribution.md](dev/distribution.md) | Which channels v1 targets and what each one constrains |
|
|
| [windows.md](dev/windows.md) | The Windows installer, cross-built from the Linux CI |
|
|
| [android-signing.md](dev/android-signing.md) | Which key signs the APK, and keeping it |
|
|
|
|
**Archive.** Kept as the record of what was asked for, not as plans.
|
|
|
|
| | |
|
|
|---|---|
|
|
| [milestone-v0.1.md](dev/archive/milestone-v0.1.md) | The first milestone, delivered 2026-08-30 and superseded |
|
|
| [ui-refinement.md](dev/archive/ui-refinement.md) | How the interface should look; succeeded by [ui-navigation.md](dev/ui-navigation.md) |
|
|
|
|
## Conventions
|
|
|
|
Three files here are generated and must not be edited by hand:
|
|
`gestures.md`, `dev/traceability.md` and `manual/index.html`, the page the
|
|
packages install, rendered from `manual/README.md`. All three come from
|
|
`cargo run -p traceability`, the pre-commit hook keeps them in step with the
|
|
tree, and CI fails when one is not what the tree generates. The manual's
|
|
pictures are recorded by [`tools/manual`](../tools/manual/README.md) and live
|
|
in LFS.
|
|
|
|
A design document links to the requirements it satisfies and to the code
|
|
that satisfies them. When the code moves, the link moves with it; a document
|
|
that has stopped being true goes to `dev/archive/` with a note saying what
|
|
replaced it, rather than being deleted.
|