Skip to content

Docs: 10-minute start, one guide per task, shorter pages - #23

Merged
timtreis merged 1 commit into
mainfrom
docs/restructure
Nov 16, 2026
Merged

timtreis merged 1 commit into
mainfrom
docs/restructure

Conversation

@timtreis

Copy link
Copy Markdown
Member

Summary: The PR restructures the docs into a 10-minute start, one guide per task, a reference section and a development section, and cuts the prose by about half. It is meant to go in before the 0.3.0 release.

Structure

  • Getting started: quickstart ("diffsvg in 10 minutes", new). It loads the example data, computes the distances, bins with organoids as replicates, runs the shape test, shows the volcano plot and curves, and runs one gene-set test. It also says what to change for your own data.
  • Guides:
    • replicates_tutorial ("Comparing conditions with replicates"): the shape, level and slope tests, how to read and check the hits, and gene sets. About 20% shorter.
    • settings_and_clustering (was full_tutorial): the stability grid and clustering. The pooled "quickstart" on the model without replicates is removed, and so is the cell-fit toggle, because cell fits test the whole distance range. Every figure and table now has a reading.
    • without_replicates (was single_slide_test): one gene against the rest, now on a control section where the anchor is a real SHH domain. The TODO notes and timings are removed, the Moran's I benchmark is cut to one paragraph, and the page says that its p-values come from cells and serve only for ranking.
  • Reference: method (with a new Validation section and citations of Legnini et al. 2023 and Wu et al. 2010), API grouped by task (main workflow, checking the settings, single samples and clustering, low-level functions), logging (was "settings") and the changelog.
  • Development: contributing.
  • Removed: test_comparison_legnini (moved to benchmarks/notebooks/ on prototype/all-prs) and the template references.md. The old URLs redirect on Read the Docs.

The README is shorter: what diffsvg does, install, and one line per guide on when to read it.

Review

The 4-persona panel (biologist, statistician, scverse maintainer, newcomer) read the rendered pages, and their findings are fixed. Examples:

  • The cell-fit toggle offered anti-conservative p-values as if they were equivalent to the bin fit.
  • The single-sample example used an SHH organoid, where the anchor is no source of SHH.
  • The settings guide claimed the defaults match the richest setting. They keep 85% of the top 20 genes, but the Spearman correlation is 0.82.
  • Hit lists differ between the guides and say why.
  • Immediate-early genes and TBP are flagged as likely technical signal.

Checks

  • All four notebooks were executed on main, with stderr and local paths stripped.
  • hatch run docs:build (-W) passes, and pre-commit passes.

@review-notebook-app

Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.04%. Comparing base (1e3f48f) to head (d345fe9).

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #23   +/-   ##
=======================================
  Coverage   88.04%   88.04%           
=======================================
  Files          15       15           
  Lines        1974     1974           
=======================================
  Hits         1738     1738           
  Misses        236      236           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@timtreis
timtreis merged commit 639678a into main Nov 16, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant