Unify doctest replay extraction and fix installed-package bootstrap

[chrizzFTD]

Summary

Phase 2 follow-up for autodoc REPL integration, addressing the two bugs found when building the naming docs.

1. Unified doctest_to_replay_source()

Single conversion function for both autodoc doctest blocks and .. py-repl:: directive bodies:

• Uses doctest.DocTestParser only — strips expected output, splits examples, joins with blank lines
• No fallback path; non-doctest input returns empty string
• Removed strip_doctest_prompts() and extract_doctest_source()

2. Installed-package bootstrap via packages=

For modules outside the Sphinx source tree, autodoc REPLs emit packages="<top-level module>" (micropip) instead of exec'ing inspect.getsource(). In-tree demo modules still use silent :src:.

Tests

pytest -v   # 20 passed

Follow-up

After merge, naming can drop the temporary pyrepl_autodoc_fix.py monkey-patch (PR chrizzFTD/naming#31).

  

[read-the-docs-community]

Documentation build overview

📚 sphinx-pyrepl-web | 🛠️ Build #33352549 | 📁 Comparing c6902e1 against latest (ef2ee2b)

  🔍 Preview build  

3 files changed

± example.html
± genindex.html
± index.html

[chrizzFTD]

@cursoragent review

[cursor]

PR Review: Unify doctest replay extraction and fix installed-package bootstrap (#13)

Verdict: Approve — ready to merge into cursor/autodoc-doctest-repl-3c18

This PR cleanly addresses both naming bugs with a smaller, more coherent surface area than the original monkey-patch approach. RTD preview builds successfully.

---

What works well

Unified extraction — doctest_to_replay_source() is a good simplification. One 12-line function, DocTestParser only, shared by autodoc and the directive. Removing strip_doctest_prompts() and the fallback eliminates the divergence that caused the naming Name syntax error.

Blank-line joining — \n\n.join(examples) is the correct fix for multiline class blocks. The naming-shaped unit test and integration tests confirm it.

Installed-package bootstrap — Replacing inspect.getsource() with packages=module_name.split(".")[0] is the right call. It aligns autodoc REPLs with Overview's working :packages: naming pattern and avoids exec'ing package source with relative imports. The new installed_pkg integration test (relative import in __init__.py) is exactly the regression we needed.

Net reduction — ~53 lines removed overall despite adding tests. Matches the stated preference for minimal, debt-free code.

Tests — 20/20 pass locally. Coverage spans unit (extraction), integration (autodoc scope, in-tree :src:, out-of-tree packages=), and existing build/replay tests still pass through the unified path.

---

Minor cleanup (optional, can follow up)

Item	Notes
Dead bootstrap_content path	_resolve_autodoc_bootstrap never returns bootstrap content anymore, but register_autodoc_repl still supports writing -bootstrap.py files. Harmless but could be removed in a small follow-up to simplify the API.
module_name.split(".")[0] heuristic	Fine for naming, repl_test_demo, etc. Fails when PyPI name ≠ import top-level (e.g. yaml → PyYAML). Worth a one-line README caveat; a pyrepl_autodoc_packages override can wait.
Silent bootstrap failure	Import/OSError still returns (None, None, None) with no Sphinx warning. User sees NameError at runtime. Low priority; same as before for the failure case.
Non-doctest directive bodies	Plain Python in .. py-repl:: (no >>>) now produces an empty replay script. Intentional and correct given the DocTestParser-only decision; worth noting in docs if not already implied.

None of these block merge.

---

Confirmed against naming issues

Original bug	Fixed by
Missing blank lines → SyntaxError after class body	doctest_to_replay_source() joins examples with \n\n
Bootstrap exec of __init__.py with relative imports	packages="naming" via micropip
Overview worked, autodoc didn't	Both paths now consistent for installed packages

After this merges into the autodoc branch and naming drops pyrepl_autodoc_fix.py, the workaround in naming#31 can be removed.

---

Summary

Area	Rating
Design	Strong — single conversion path, removes broken bootstrap strategy
Correctness	Good — addresses both root causes with targeted tests
Minimalism	Strong — deletes more code than it adds
Docs	Adequate — README/example.rst updated for in-tree vs installed bootstrap
CI / RTD	Green — preview build available

Recommendation: Merge into cursor/autodoc-doctest-repl-3c18, then proceed with naming validation (Phase 3). Optional follow-up PR to drop the unused bootstrap_content machinery.