Fill empty stubs in output and configuration docs

[riasc]

Summary

Changed

docs/output.md — fills the empty section headers that were carried over from the wiki as placeholders:

• PRE-PROCESSING: what FastQC + fastp produce and where, with per-group / per-readpair filename conventions.
• HLA: completes the two truncated sentences. The first now explains the three source labels (DNA / RNA / custom) on each row of mhc-{I,II}.tsv; the second notes that downstream binding-affinity prediction uses the deduplicated allele set.
• ALIGNMENT: distinguishes the DNA path (BWA direct) from the RNA path (STAR chimeric → BWA realign) and explains why the realign step exists (downstream RNA callers need a BWA-style CIGAR).
• ALTERNATIVE SPLICING: SplAdder intermediates + the per-group VCF augmentation pattern (GRP / SRC keys) + the merged altsplicing.vcf.gz output.
• INDEL/SNVs: transIndel (long indels, RNA) vs Mutect2 (short indels + SNVs, DNA), with a pointer to the indel.type / indel.mode config keys that gate them.

docs/configuration.md — adds the descriptions that were missing under the two YAML examples:

• HLA GENOTYPING: parameter table for the three *_mode values (DNA / RNA / custom), how combinations work, and a paragraph on freqdata / split / dict pointing at HLA-HD plus the workflow-load check from PR Check HLA-HD setup at workflow-load time #151.
• PRIORITIZATION: paragraph on class (with a cross-reference to the subset-of-hlatyping rule from PR Cross-field config consistency checks at workflow-load time #152) and lengths (the netMHCpan / netMHCiipan k-mer windows; both discrete-list and range syntax accepted).

Stubs deliberately left as stubs

• developer.md — one-page index of wildcards and scripts; thin but not misleading.
• resources.md — single pathogen-derived TSV note; same.
• troubleshooting.md — currently has only the apptainer-user-namespace entry from PR Scaffold MkDocs Material docs site (GH Pages) #154; expanding into a real FAQ is a separate scope.

Second PR against #147. Third PR (link-check CI + per-tag versioning via mike + wiki "see new site" notice) is still pending.

QC

• I, as a human being, have checked each line of code in this pull request
• mkdocs build --strict clean locally
• All five live pages still render (build job will re-confirm on this PR)

Summary by CodeRabbit

• Documentation
  • Expanded HLA genotyping configuration documentation with detailed explanations of class selection, allele prediction modes, and error detection.
  • Added prioritization configuration documentation covering class constraints and k-mer length definitions.
  • Completely reworked output documentation with comprehensive walkthrough of all ScanNeo2 output files and formats, including quality control, alignment, and variant calling results.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation-only update to docs/configuration.md and docs/output.md. The configuration docs gain explanatory text for HLA genotyping mode controls and prioritization class/length constraints. The output docs replace placeholder headings with a complete, ordered walkthrough of every ScanNeo2 pipeline stage output.

Changes

ScanNeo2 Documentation Expansion

Layer / File(s)	Summary
HLA Genotyping and Prioritization config docs docs/configuration.md	Adds explanatory text for class, MHC-I_mode/MHC-II_mode, HLA-HD prerequisite validation at workflow-load time, the prioritization.class⊆hlatyping.class constraint, and lengths.MHC-I/lengths.MHC-II k-mer format and defaults.
Full pipeline output walkthrough docs/output.md	Replaces stub headings with complete subsections for pre-processing (FastQC reports, fastp naming conventions), HLA typing tables (mhc-I.tsv/mhc-II.tsv format), DNA/RNA alignment flow (STAR→BWA realignment for RNA), and variant calling outputs (SplAdder, ScanExitron with GRP/SRC INFO fields, transIndel, Mutect2) including indel.type/indel.mode controls.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hippity-hop through the docs we go,
Where HLA modes and k-mer lengths flow,
The outputs now written, no stubs in sight,
From FastQC reports to variants at night,
This rabbit's quite pleased with the pipeline's new glow! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fill empty stubs in output and configuration docs' accurately describes the main change: completing documentation in two key files by replacing placeholder sections with comprehensive content covering pre-processing, HLA, alignment, variant calling, and configuration parameters.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fill-stubs-147

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[riasc]

Review summary (self-review)

CI build job green; deploy correctly skipping on the PR branch. CodeRabbit hit a rate-limit and didn't post a review — not actionable.

One self-caught correction (already pushed)

The first commit attributed transIndel to RNA-seq only, but indel.smk has both detect_long_indel_ti_build_DNA and detect_long_indel_ti_build_RNA; modality is set by indel.mode. Fixed in 49b3c1a — section now attributes the two callers (transIndel + Mutect2) without over-constraining the modality, and mentions the per-split-BAM parallelism in Mutect2 as a real behavioural detail.

Other claims worth flagging for human re-check

• Filenames I assert in PRE-PROCESSING (<group>_preproc.fq.gz / <group>_preproc_r1.fq.gz / <group>_preproc_r2.fq.gz): based on the SE / PE preproc_* rule outputs in preproc.smk. Probably right but worth a glance.
• mhc-{I,II}.tsv example with mixed DNA / RNA / custom source labels: the original wiki only showed custom rows. Mixing was inferred from the *_mode semantics — a DNA, RNA, custom mode should produce all three source labels. Worth verifying on a real run that combines sources.
• Cross-references to PRs Check HLA-HD setup at workflow-load time #151 and Cross-field config consistency checks at workflow-load time #152: those checks are in common.smk on main now, so the references are stable.

Stubs left as stubs (deliberate)

developer.md, resources.md, and troubleshooting.md (beyond the apptainer entry from #154) — out of scope for this PR.

Findings

No correctness bugs uncovered beyond the self-caught one. The two flagged items above are claims I'd want a quick human sanity-check on rather than bugs.

[coderabbitai]

🧹 Nitpick comments (1)

docs/output.md (1)

43-48: 💤 Low value

Add language specifier to code block for linting compliance.

The fenced code block lacks a language tag. While the content is valid, the markdownlint tool flags this for consistency (MD040).

📝 Proposed fix

-```
+```tsv
 DNA       HLA-A*02:01
 RNA       HLA-A*02:01
 custom    HLA-A*02:01
 custom    HLA-B*15:07
-```
+```

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/output.md` around lines 43 - 48, The fenced code block containing the
DNA, RNA, and custom HLA type data is missing a language specifier on the
opening fence, which triggers the markdownlint MD040 rule. Add the language
identifier tsv to the opening triple backticks to indicate this is tab-separated
values content and ensure compliance with markdown linting standards.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/output.md`:
- Around line 43-48: The fenced code block containing the DNA, RNA, and custom
HLA type data is missing a language specifier on the opening fence, which
triggers the markdownlint MD040 rule. Add the language identifier tsv to the
opening triple backticks to indicate this is tab-separated values content and
ensure compliance with markdown linting standards.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d41d2d42-8759-43bf-b87c-79d92193ee3a

📥 Commits

Reviewing files that changed from the base of the PR and between be4aec7 and 49b3c1a.

📒 Files selected for processing (2)

• docs/configuration.md
• docs/output.md