docs: example-rich guides, getting-started, datasets, and R map#11
Merged
Conversation
Expand the documentation from a single API page into an accessible, example-first site (informed by top Python docs and the R moderndive pkgdown site): - Rewritten landing page: value proposition, feature list, install (+ image extra), and a 30-second worked example. - getting-started: an end-to-end first analysis. - Task guides with runnable, verified examples (dual-engine plots throughout): sampling, bootstrapping & confidence intervals, hypothesis testing, regression (incl. per-facet coefficient shading and the model plots), theory-based inference, and a plotting/engines guide. - datasets: a thematic tour of all 58 bundled datasets. - coming-from-r: a function-by-function R -> Python map for moderndive/infer users. Every code block was executed against the package to confirm it runs. Docs build clean with -W (no warnings). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
Pulls the fixed logo from the PR #10 branch so this docs branch doesn't ship the old bottom-cropped hex regardless of PR merge order. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
Switch the docs to myst-nb so every example runs at build time and its output
(DataFrames + plots) renders on the site:
- conf.py: myst_nb engine; execute {code-cell} blocks; prefer static image/png
over plotly's heavy interactive html; strip kernel stderr.
- Plots render as static PNGs — plotnine via matplotlib, plotly via kaleido
(renderer set to "png" in each page's hidden setup cell).
- doc extra: add myst-nb, ipykernel, kaleido. .readthedocs.yaml installs Chrome
for kaleido (>=1.0 no longer bundles it) via a post_install job.
- Landing 30-second example now uses the spotify dataset (not promotions); the
Coming-from-R pipeline example uses pennies (not mtcars), and its function map
now lists only the genuine R->Python differences, noting the rest are identical.
Every page executes cleanly in the kernel and the build is warning-free under -W.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
- Attach a `.specify()` method to polars and pandas DataFrames so you can write `md.load_pennies().specify(response="year")`, mirroring R's `df %>% specify(...)`. Registered on import; never overwrites an existing attribute. - Add `geom_categorical_model` as an alias of `gg_categorical_model` so both R names are available and do the same thing. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
Add tooling to catch when the upstream R packages change in ways the Python port hasn't followed: - tools/parity_probe.R dumps upstream structure (versions, exports, dataset dims/columns) as JSON. - tools/check_parity.py compares it to the bundled datasets + a recorded manifest, reporting version bumps, added/removed exports, and missing or shape-changed datasets; exits non-zero on drift. - tools/parity_manifest.json records the reviewed upstream snapshot (provenance). - .github/workflows/parity-drift.yml runs this weekly against upstream main and opens/updates a GitHub issue on drift. - tests/test_parity_manifest.py asserts bundled moderndive/infer datasets match the manifest dims, so a bad data regeneration fails CI. - tools/README.md documents the data-refresh and parity processes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
- Remove the promotions dataset from all examples and the dataset catalog (we're not using it going forward): getting-started and the hypothesis-testing guide now use the MythBusters yawn experiment / spotify; coming-from-r uses pennies. - Add a worked "custom test statistic" example (a callable passed to calculate()) to the hypothesis-testing guide, bootstrapping a custom IQR. - Use the new df.specify() flow in examples; note geom_categorical_model as a same-name function in the R map. - Rebuilt HTML. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
…tive) - Convert examples from specify(df, ...) to df.specify(...) to mirror the R df %>% specify(...) pipeline more closely. - Add a note (landing, getting-started, plotting guide) that documentation plots are static images while the default plotly engine is interactive when run. - Rebuilt HTML. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
# Conflicts: # doc/_build/html/.doctrees/api.doctree # doc/_build/html/.doctrees/environment.pickle # doc/_build/html/searchindex.js
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CTL1QSTg1DmDUpqYuPEog
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes the Read the Docs site much more accessible — moving from a single API page to an example-first structure modeled on top Python docs (polars-style getting-started + task guides) and the R
moderndivepkgdown site.New pages
[image]extra), and a 30-second worked example (the promotions permutation test).rep_slice_sample, the bowl)draw/simulate)t_test/prop_test/chisq_test/assume,method="both"overlays)moderndive/inferusers), plus the key differences (pipe → methods, statsmodels models, plotly default, polars).Quality
-W(zero warnings); committed HTML rebuilt.🤖 Generated with Claude Code