Docs: run examples as doctests, fix drifted calls, link API objects

[tony]

Summary

• Fix seven documented calls that raise TypeError or return nothing when copied — branches.create() and set_url() shown positionally where keywords are required, notes.add(object=...)/get(object=...) for what is named object_sha, reflog.ls(ref=...) and expire(ref=...) parameters that don't exist, worktrees.add(branch=...), and QueryList filter examples using attributes the objects don't have
• Convert every runnable-shaped ```python block under docs/ into fixture-backed doctests, so pytest executes docs examples on every run — the drift above went unnoticed precisely because these blocks never ran
• Add first-mention MyST cross-references for classes, methods, and exceptions across topic, hub, and reference pages per the docs/AGENTS.md linking rule; man-page citations link to upstream docs
• Repair url/registry.md: its narration sat inside one fenced code block, rendering as monospace with unprocessed markup — now three self-contained, narrated doctest stories
• Rewrite concept-first openings for url/index.md and the cmd/sync hub pages; one-line stub pages state what each module does
• Fix project/workflow.md commands that don't work (uv install -E … → uv sync, bare uv run ruff) and replace its stale RST-era Releasing section with a pointer to the current release page

docs/AGENTS.md codifies the voice and cross-reference standard distilled from topics/traversing_git.md; this brings the remaining pages into compliance — and doubles as a regression net, since examples that execute can't silently drift from the API again.

Changes by area

Executable examples

• docs/cmd/git/*.md: each subcommand page's example is a doctest session against example_git_repo, with prose introducing each block instead of inline comments; the API-drifted calls were corrected in the process
• docs/quickstart.md: init/clone/status and Manager examples run; a new Parse URLs section delivers the URL parsing the landing-page card promises
• docs/index.md: the "At a glance" GitURL block executes
• docs/internals/query_list.md: filter examples use real attributes (branch_name) and demonstrate nested lookups with plain data
• docs/topics/traversing_git.md: the one forbidden # doctest: +SKIP replaced with a deterministic loop

Cross-references

• First prose mentions of QueryList, filter(), get(), ObjectDoesNotExist, MultipleObjectsReturned, GitURL/HgURL/SvnURL, is_valid(), to_url(), BaseSync, and urllib.parse carry the most specific role
• "Manager/Cmd pattern" mentions link to the traversing-git-repos topic; .md-style links replaced with {ref}/{doc} roles
• Man pages linked uniformly across the cmd/ and url/ families; external projects (Django, pip VCS support, pytest-xdist, Mercurial, Subversion) linked at first mention

Page voice

• docs/url/registry.md: concept-first intro naming ParserMatch/VCSRegistry, real headings replacing bold pseudo-headings, is_explicit explained
• docs/url/index.md: precision fixes ride along — Python-2 urlparse → urllib.parse, mismatched cb: shorthand example, truncated sentence, comment inside a console block, garbled clone transcript
• Hubs and stubs: cmd/index.md and sync/index.md open with what the layer does before external comparisons; one-line stubs name and link their class

Meta pages

• docs/project/workflow.md: working setup/lint commands; Releasing section deduplicated to a pointer at the release page
• docs/index.md, docs/api/index.md: pin examples refreshed to the current release range
• CHANGES: two Documentation deliverables recorded under the unreleased header

Design decisions

• Shape assertions over exact output: doctests assert stable shapes (len(...) >= 1, isinstance, +ELLIPSIS) or reuse expected output from already-passing docstring doctests, keeping them robust across git versions while still executing every call
• One story per fence: each fenced block under docs/ collects as its own doctest item with fresh fixtures, so multi-step narratives stay inside a single self-contained block rather than sharing state across fences
• Submodule add not demonstrated inline: git blocks file:// submodules by default (protocol.file.allow), so the page defers to the autodoc'd runnable examples for add/init/update instead of a doctest that would have to tolerate a fatal error

Verification

No skipped doctests remain under docs:

rg 'doctest: \+SKIP' docs

No placeholder repositories remain in examples:

rg "path='/path/to/repo'" docs

Test plan

• uv run py.test --reruns 0 — full suite including every docs doctest (docs/ and README.md are pytest testpaths)
• uv run ruff check ., uv run ruff format ., uv run mypy . — clean
• just build-docs — all new {class}/{meth}/{exc}/{ref}/{doc} targets resolve; the only warning is the pre-existing doc-pytest-plugin directive notice on an untouched page
• Rendered url/registry page shows narration as paragraphs with three separate code blocks (was one monolithic block)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.26%. Comparing base (36eb81d) to head (663c940).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #540      +/-   ##
==========================================
+ Coverage   61.18%   61.26%   +0.07%     
==========================================
  Files          40       40              
  Lines        6557     6557              
  Branches     1103     1103              
==========================================
+ Hits         4012     4017       +5     
+ Misses       1948     1946       -2     
+ Partials      597      594       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 1 issue:

1. The new changelog entry groups reflog.ls(ref=...) together with expire(ref=...) as parameters that don't exist, but GitReflogManager.ls does accept ref (ref: str = "HEAD") — only expire (keyword-only, no ref) is actually broken. The entry misstates the reflog.ls() API surface. (bug due to src/libvcs/cmd/git.py: def ls(self, ref: str = "HEAD", *, number=...))

libvcs/CHANGES

Lines 29 to 35 in a1900a0

	conversion surfaced and fixed documented calls that had drifted from the
	API: `git.branches.create()` and `remote.set_url()` shown positionally
	where keyword arguments are required, `notes.add(object=...)` for what is
	named `object_sha`, `reflog.ls(ref=...)` and `expire(ref=...)` parameters
	that don't exist, `worktrees.add(branch=...)` for `new_branch`, and
	{class}`~libvcs._internal.query_list.QueryList` filter examples using
	attribute names the objects don't have.

Source evidence that reflog.ls accepts ref:

libvcs/src/libvcs/cmd/git.py

Lines 8244 to 8249 in a1900a0

	def ls(
	self,
	ref: str = "HEAD",
	*,
	number: int | None = None,
	) -> QueryList[GitReflogEntry]:

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}