[gouyt13]

Summary

A pass over the repository docs and the documentation site, checked against the code at bac860d, plus a refresh of the benchmark pages. The three commits can be reviewed separately.

ci: deploy docs on every main push and fix stale script paths

• docs.yml: main pushes always build and deploy. Before, a newer push without docs changes could cancel a docs-changing run, and its own diff would skip the deploy, leaving the site behind main. The workflow contract test checks the new condition.
• ci_changes.py: remove the deleted benchmarks/plot_homepage.py and update its tests.
• sample/run_cpp.sh: extract the GIST archive into ./data, as run_python.sh does. The archive has a top-level gist/ directory.
• DBPEDIA_MANIFEST.json: the source field now names the file the downloader actually fetches.

docs: align documentation with the current code

• Fix statements that no longer match the code:
  • Encoders: preconditions of the advanced encoders. They do not check finiteness, and quantize_scalar does not check the code width.
  • HNSW: ef/pool clamping, add capacity, M validation, cluster_id_of.
  • IVF: k limit.
  • Wheels: OpenMP bundling.
• Contributor docs:
  • ctest --no-tests=error throughout;
  • the clang-tidy recipe matches CI;
  • Ruff for .github/scripts;
  • CI routing, ccache scope and title rules;
  • test layout;
  • HNSW accessor naming and the FFHT attribution note in docs/development.md.
• Add the missing 0.7.1 release notes, based on v0.7.0..v0.7.1 and PRs IVF per cluster storage #140, Fix parallel index execution and zero-range quantization #142–Limit IVF append metadata work to affected clusters #145 and perf(symqg): complete degrees with worker-local reverse candidates #156.
• README links use absolute site/GitHub URLs so they also work on PyPI, where the README is the long description.
• Remove an unreferenced image.

docs: lead benchmark pages with results and redraw QPS-recall figures

• Benchmark pages show results before setup and reproduction details. The overview opens with GIST1M key results.
• QPS–recall figures:
  • One panel per storage class: codes with float32 reranking, about 4 bits, about 8 bits.
  • Validated three-color palette, with line style and marker as a second encoding.
  • Recall axis from 0.5 where possible; legends below the panels.
  • The subtitle CPU comes from the build records; selections with mixed CPUs are rejected.
• The four SVGs were regenerated from the committed qps-recall-points.csv with the new plot_family(). No new measurements were taken; the raw records are not available locally, so the CPU string follows /proc/cpuinfo format.
• Home page: one sentence on the error-bound guarantee, and GIST1M numbers on each index card, recomputed from the CSVs.
• Layout:
  • Tables, code and figures use a 44rem column; prose stays at 34rem.
  • Charts scroll sideways on narrow screens.
• Corrections to benchmark setup statements:
  • the installer builds with native optimization ON;
  • the runners require the recorded host and thread layout;
  • training-time columns;
  • the 0.7.1 raw records are not published.

No API, saved-index format or dependency changes.

Testing

• python -m mkdocs build --strict --config-file docs/mkdocs.yml: no warnings. Layout checked in headless-browser screenshots at 1440 px and 390 px, light and dark.
• ./scripts/check-python.sh, plus ruff format --check and ruff check on .github/scripts: pass.
• python -m unittest discover -s .github/scripts -p 'test_*.py': 60 tests OK.
• python -m pytest tests/python/test_benchmark_protocol.py: 14 passed. The two new plot tests use pytest.importorskip("matplotlib"), so they are skipped in the Python quality job, which does not install matplotlib.
• shellcheck sample/run_cpp.sh and git diff --check: clean.
• Not run:
  • sample/run_cpp.sh end to end (it needs the 2.7 GB GIST download). The fix is based on the archive layout and run_python.sh.
  • The benchmark suite (no new measurements).