docs: add obikmer user guide and MkDocs build configuration

Introduces a comprehensive documentation set covering theoretical foundations, CLI usage, installation, and system architecture. Adds MkDocs configuration and Makefile targets to generate, serve with live reload, and clean the documentation site. Includes citation styles and bibliography files for academic references.
2026-08-13 17:19:01 +02:00
parent 0c86ea0385
commit 6acafa7f2c
28 changed files with 1497 additions and 1 deletions
@@ -0,0 +1,38 @@
+# query
+
+Query an index with sequences and annotate each query with the kmer matches found.
+
+```bash
+obikmer query INDEX INPUTS... [OPTIONS]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `INDEX` | Index directory to query against |
+| `INPUTS...` | Input sequence files (FASTA/FASTQ, gzip optional); at least one required |
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--detail` | off | Report per-position, per-genome coverage vectors in the output |
+| `--count-missing` | off | Also count query kmers absent from the index |
+| `--force-presence` | off | Report presence (0/1) per genome instead of raw counts |
+| `--presence-threshold` | `1` | Minimum accumulated count to declare a genome present (implies `--force-presence`) |
+| `-z, --findere-z` | derived from the index metadata | Override the Findere z parameter |
+| `-T, --threads` | detected core count | Number of worker threads |
+| `--chunk-size` | auto-sized (available RAM ÷ threads, clamped to 4–256 MiB) | I/O chunk size, in MiB |
+| `--max-open-files` | `threads / 4` (min 1) | Maximum number of input files open simultaneously |
+
+## Output
+
+FASTA on stdout, one record per query, annotated in the OBITools-style header format `>id {"key":value,...}`:
+
+- `kmer_count`: total number of kmers matched
+- `kmer_missing`: number of query kmers absent from the index (only with `--count-missing`)
+- `kmer_strict_matches`: per-genome match counts
+- `coverage`: per-position, per-genome coverage vectors (only with `--detail`)
+
+`--mismatch` is accepted by the CLI but not currently functional; using it produces a warning and is ignored.