Skip to content

Docs: uv-first install guide, chain-first tutorials, and fixes#463

Open
peterrrock2 wants to merge 8 commits into
misc/odds-and-ends-pt2from
docs/update_venv_and_mc_usage
Open

Docs: uv-first install guide, chain-first tutorials, and fixes#463
peterrrock2 wants to merge 8 commits into
misc/odds-and-ends-pt2from
docs/update_venv_and_mc_usage

Conversation

@peterrrock2

Copy link
Copy Markdown
Collaborator

Summary

Major rewrite of the installation guide to give better instruction on how to work with virtual
environments. Changes to the other tutorials were intentionally kept minimal; the MarkovChain
examples were converted to the incremental "build the chain first" style, but rewording of the
surrounding narrative was limited to what was necessary.

Docs are ready for more serious edits from @chief-dweeb after this. It was faster for me to just
make the minimal changes that I wanted than it was for me to add the notes in.

Brings the user guide in line with the 1.0.0 API and tooling: an installation guide rewritten around
uv, the tutorials converted to the incremental "build the chain first" style, and a set of small doc
and repository fixes. Documentation-only. Stacks on misc/odds-and-ends-pt2.

Why

Three gaps had opened up between the docs and the current library:

  • The install guide still assumed a hand-managed python -m venv and contradicted itself once uv
    guidance was added.
  • The tutorials still constructed MarkovChain all at once, rather than the incremental paradigm
    introduced in recom.ipynb.
  • The README advertised a gerrychain[geo] extra that no longer exists, and a stalled ReCom chain
    had no user-facing explanation.

Changes

  • Rewrote docs/user/install.md around uv (uv init / uv add, uv run, git installs), keeping
    pip + python -m venv as the alternative, and added a "Checking Your Installation" section with
    copyable preflight checks and a notebook-kernel check.
  • Converted the MarkovChain examples in quickstart.ipynb, data.ipynb, geometries.ipynb,
    reproducibility.md, and generate_recom_assets.py to instantiate the chain first and configure
    it incrementally, with the surrounding narrative rewritten to explain each piece as it is
    attached.
  • Added a "When epsilon is the real problem" section to recom.ipynb explaining that a stalled
    chain means cuttable trees are rare, not impossible.
  • Removed the obsolete gerrychain[geo] and geo_settings.txt instructions from the README, and
    gitignored the local PA_VTDs.json tutorial copy and the PA_output.jsonl that data.ipynb
    writes when executed.
  • Added the python notebooks into the formatting task in the makefile.

Testing

  • Docs build cleanly (make docs, warnings-as-errors)
  • Manually tested relevant behavior

Ran make docs and make docs-test, confirmed committed notebooks carry no outputs, re-executed
each converted notebook into the ignored MyST-NB cache, and ran the install commands and preflight
checks end-to-end in fresh projects across the released, git, and development versions.

@peterrrock2
peterrrock2 requested a review from chief-dweeb July 19, 2026 21:20
@peterrrock2
peterrrock2 marked this pull request as draft July 19, 2026 22:08
@peterrrock2
peterrrock2 marked this pull request as ready for review July 19, 2026 22:19
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