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,27 @@
+# superkmer
+
+Extract super-kmers from one or more sequence files and write them to stdout, without building a full index. Useful for inspecting or piping the super-kmer decomposition of a dataset.
+
+```bash
+obikmer superkmer [OPTIONS] [INPUTS...]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `INPUTS...` | Input sequence files or directories (FASTA/FASTQ/GenBank, gzip optional). If omitted, reads from stdin. |
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `-k, --kmer-size` | `31` | Kmer size (must be odd, in [11, 31]) |
+| `-m, --minimizer-size` | `11` | Minimizer size (must be odd, in $[3, k-1]$) |
+| `--theta` | `0.7` | Entropy threshold; kmers with a normalized entropy at or below this value are excluded |
+| `--level-max` | `6` | Maximum sub-word size used for the entropy score |
+| `-p, --partitions` | `256` | Number of partitions (rounded up to the next power of 2) |
+| `-T, --threads` | detected core count | Number of worker threads |
+| `--max-open-files` | `threads / 4` (min 1) | Maximum number of input files open simultaneously |
+
+Output is written to stdout in the internal scatter format used by `index`; it is primarily intended to be piped into other tools or inspected for debugging.