-
-- :material-download: **[Install](getting-started/installation.md)**
-
- Build from source or take a tagged binary. Needs Rust and minimap2.
-
-- :material-school: **[Tutorial](getting-started/tutorial.md)**
-
- A full run on a generated dataset with known problems planted in it.
-
-- :material-rocket-launch: **[Quick start](getting-started/quickstart.md)**
-
- One command for a publication-grade correction pass, and what to read first.
-
-- :material-tune: **[Matrix policies](guide/matrix-policies.md)**
-
- Which evidence reaches the binary matrix, and how to word it in a paper.
-
-- :material-chart-box: **[Run report](guide/report.md)**
-
- The self-contained HTML viewer: phylogeny, matrix and synteny in one page.
-
-- :material-table: **[Output files](guide/outputs.md)**
-
- Every table Recore writes, column by column, with coordinate conventions.
-
-- :material-dna: **[How it works](how-it-works/algorithm.md)**
-
- Each pipeline phase, the data structures behind it, and the complexity.
-
-
-
-## What a run gives you
-
-```bash
-recore \
- -p gene_presence_absence.csv \
- -r pan_genome_reference.fa \
- -g genomes/ \
- -a annotations/ \
- --synteny --multi-allele --nscluster \
- --matrix-policy balanced \
- --reference-genome AS00146 \
- --write-html-report \
- -t 8 -o recore_output/
-```
-
-| Read this first | For |
-|-----------------|-----|
-| `gene_presence_absence_recore.csv` | the corrected binary matrix, for downstream tools |
-| `gene_presence_absence_recore.Rtab` | the same matrix as 1/0, for pyseer and Rtab readers |
-| `gene_presence_absence_recore_states.csv` | audit and figures, one biological state per cell |
-| `orthology_evidence.tsv` | publication wording and manual review |
-| `recore_report.html` | a self-contained viewer for the whole run |
-| `evolutionary_events.tsv` | acquisition, loss, IS interruption, pseudogene or paralog per cluster |
-
-The full list, with every column, is in [Output files](guide/outputs.md).
-
-## What Recore does not claim
-
-Recore is not a pangenome caller and it does not replace one. It cannot invent
-evidence that is absent from the assembly sequence, it does not decide that a
-partial homologue is a functional gene, and it does not force an ancestral story
-onto an ambiguous phylogenetic pattern. Everything it declines to correct is
-still written down. See [Limits and comparisons](how-it-works/limits.md).
-
-## Citation
-
-> Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control
-> of pangenome presence/absence matrices. *In preparation.*
diff --git a/docs/reference.html b/docs/reference.html
new file mode 100644
index 0000000..5649829
--- /dev/null
+++ b/docs/reference.html
@@ -0,0 +1,256 @@
+
+
+
+ and
+ self.blocks: dict[str, str] = {}
+ self.option_rows: list[list[str]] = []
+ self._code_depth = 0
+ self._code_open: list[tuple[str, list[str]]] = []
+ self._capture: list[tuple[str, int, list[str]]] = []
+ self._depth = 0
+ self._row: list[str] | None = None
+ self._cell: list[str] | None = None
+ self._in_options = False
+
+ def handle_starttag(self, tag, attrs):
+ a = dict(attrs)
+ self._depth += 1
+ if "id" in a:
+ self.ids.add(a["id"])
+ for key in ("href", "src"):
+ if key in a and a[key] is not None:
+ self.links.append((tag, a[key]))
+ remote = lambda url: url and re.match(r"^(https?:)?//", url)
+ if tag == "link" and "stylesheet" in (a.get("rel") or "") and remote(a.get("href")):
+ self.remote_assets.append(a["href"])
+ if tag in ("script", "img", "iframe") and remote(a.get("src")):
+ self.remote_assets.append(a["src"])
+ if tag in ("code", "pre"):
+ self._code_depth += 1
+ self._code_open.append((tag, []))
+ if tag == "pre" and a.get("data-copy-source"):
+ self._capture.append((a["data-copy-source"], self._depth, []))
+ if tag == "div" and "out" in (a.get("class") or "").split():
+ self._capture.append(("out", self._depth, []))
+ if tag == "table" and a.get("id") == "options-table":
+ self._in_options = True
+ if self._in_options and tag == "tr":
+ self._row = []
+ if self._in_options and tag in ("td", "th") and self._row is not None:
+ self._cell = []
+ if tag == "br" and self._capture:
+ self._capture[-1][2].append("\n")
+
+ def handle_endtag(self, tag):
+ if tag in ("code", "pre"):
+ self._code_depth = max(0, self._code_depth - 1)
+ if self._code_open and self._code_open[-1][0] == tag:
+ kind, parts = self._code_open.pop()
+ self.code_elems.append((kind, "".join(parts)))
+ if self._capture and self._capture[-1][1] == self._depth and tag in ("pre", "div"):
+ name, _, parts = self._capture.pop()
+ self.blocks[name] = "".join(parts)
+ if self._in_options and tag in ("td", "th") and self._cell is not None and self._row is not None:
+ self._row.append("".join(self._cell).strip())
+ self._cell = None
+ if self._in_options and tag == "tr" and self._row is not None:
+ self.option_rows.append(self._row)
+ self._row = None
+ if tag == "table":
+ self._in_options = False
+ self._depth -= 1
+
+ def handle_data(self, data):
+ if self._code_depth:
+ self.code_text.append(data)
+ for _, parts in self._code_open:
+ parts.append(data)
+ for _, _, parts in self._capture:
+ parts.append(data)
+ if self._cell is not None:
+ self._cell.append(data)
+
+
+def parse(path: Path) -> Page:
+ page = Page()
+ page.feed(path.read_text(encoding="utf-8"))
+ return page
+
+
+def help_options(recore: str) -> tuple[set[str], set[str], dict[str, str]]:
+ """Long options, short options and defaults that `recore --help` prints."""
+ out = subprocess.run([recore, "--help"], check=True, capture_output=True, text=True).stdout
+ longs = set(re.findall(r"(? list[str]:
+ problems = []
+ for name, page in pages.items():
+ for url in page.remote_assets:
+ problems.append(f"{name}: loads {url} from another host; the site must work offline")
+ for tag, url in page.links:
+ if re.match(r"^(https?:|mailto:)", url):
+ continue
+ target, _, anchor = url.partition("#")
+ if not target:
+ if anchor and anchor not in page.ids:
+ problems.append(f"{name}: link to #{anchor}, which no element on the page has")
+ continue
+ path = SITE / target
+ if not path.exists():
+ problems.append(f"{name}: <{tag}> points at {target}, which does not exist")
+ continue
+ if anchor and target in pages and anchor not in pages[target].ids:
+ problems.append(f"{name}: link to {target}#{anchor}, which no element there has")
+ return problems
+
+
+def check_flags(pages: dict[str, Page], recore: str) -> list[str]:
+ problems = []
+ longs, shorts, defaults = help_options(recore)
+ mentioned_long: dict[str, str] = {}
+ mentioned_short: dict[str, str] = {}
+
+ def note(text: str, where: str) -> None:
+ for flag in re.findall(r"(? list[str]:
+ problems = []
+ for path in [SITE / p for p in PAGES] + SCRIPTS:
+ for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+ if "\u2014" in line:
+ problems.append(f"{path}:{number}: em-dash")
+ return problems
+
+
+def check_tutorial(pages: dict[str, Page], recore: str) -> list[str]:
+ """Run the Try-it commands as the page shows them and compare the counts."""
+ index = pages["index.html"]
+ script = index.blocks.get("try")
+ promised = index.blocks.get("out")
+ if not script or not promised:
+ return ["index.html: no Try-it block or no expected output block to check"]
+ want = {
+ key: re.search(rf"^{key}:\s+(\d+)", promised, flags=re.M)
+ for key in ("Rescued", "Matrix-corrected")
+ }
+ if not all(want.values()):
+ return ["index.html: the expected output does not show Rescued and Matrix-corrected counts"]
+ commands = []
+ for line in script.replace("\\\n", " ").splitlines():
+ line = line.strip()
+ if line.startswith("$ "):
+ line = line[2:]
+ if not line:
+ continue
+ if line.startswith("curl ") and DATASET_SCRIPT.name in line:
+ commands.append(["cp", str(DATASET_SCRIPT.resolve()), "."])
+ continue
+ words = line.split()
+ if words[0] == "recore":
+ words[0] = str(Path(recore).resolve())
+ commands.append(words)
+ with tempfile.TemporaryDirectory() as work:
+ for words in commands:
+ run = subprocess.run(words, cwd=work, capture_output=True, text=True)
+ if run.returncode != 0:
+ return [f"Try it: `{' '.join(words)}` failed:\n{run.stderr[-2000:]}"]
+ summary = Path(work, "tutorial_out", "summary.txt")
+ if not summary.exists():
+ return ["Try it: the commands ran but wrote no tutorial_out/summary.txt"]
+ text = summary.read_text()
+ problems = []
+ for key, match in want.items():
+ got = re.search(rf"^{key}:\s+(\d+)", text, flags=re.M)
+ if not got or got.group(1) != match.group(1):
+ problems.append(
+ f"Try it: the page promises {key}: {match.group(1)}, the run gave "
+ f"{got.group(1) if got else 'nothing'}"
+ )
+ return problems
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--recore", default="target/debug/recore", help="the recore binary to read --help from")
+ parser.add_argument("--run-tutorial", action="store_true", help="also run the Try-it commands (needs minimap2)")
+ args = parser.parse_args()
+
+ pages = {name: parse(SITE / name) for name in PAGES}
+ problems = check_links(pages) + check_flags(pages, args.recore) + check_dashes()
+ if args.run_tutorial:
+ if not shutil.which("minimap2"):
+ problems.append("Try it: minimap2 is not on PATH")
+ else:
+ problems += check_tutorial(pages, args.recore)
+ if problems:
+ print("The website does not match the code:", file=sys.stderr)
+ for problem in problems:
+ print(f" {problem}", file=sys.stderr)
+ return 1
+ checked = "links, options, defaults, dashes" + (", and the Try-it run" if args.run_tutorial else "")
+ print(f"docs/: {checked} all agree with the code")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/make_logo_variants.py b/tools/make_logo_variants.py
index a5827ca..36ae4f4 100644
--- a/tools/make_logo_variants.py
+++ b/tools/make_logo_variants.py
@@ -31,8 +31,8 @@
# carrying a second copy of a 30 KB asset. These markers bracket the generated
# rules so regenerating cannot drift from the dark file.
REPORT_CSS = ROOT / "src" / "pipeline" / "report_assets" / "report.css"
-# MkDocs only serves what lives under docs/, so the two variants are copied
-# there rather than kept in a second place by hand.
+# The website only serves what lives under docs/, so the two variants are
+# copied there rather than kept in a second place by hand.
DOCS_ASSETS = ROOT / "docs" / "assets"
CSS_BEGIN = "/* >>> generated by tools/make_logo_variants.py */"
CSS_END = "/* <<< generated */"
@@ -195,7 +195,7 @@ def main() -> int:
print(f"{REPORT_CSS.relative_to(ROOT)} {rules:>6} generated rules")
print(f"{LIGHT.relative_to(ROOT)} {len(light):>6} bytes")
print(f"{DARK.relative_to(ROOT)} {len(dark):>6} bytes")
- print(f"{DOCS_ASSETS.relative_to(ROOT)}/ {'':>6} both copied for MkDocs")
+ print(f"{DOCS_ASSETS.relative_to(ROOT)}/ {'':>6} both copied for the website")
print()
print(f"{'ink':>16} {'lifted to':>9} {'was':>5} {'now':>5}")
for before, after in sorted(mapping.items()):
+ 
+