Add opt-in autodoc integration for Example doctest blocks (v0.2.0)

[chrizzFTD]

Summary

Closes #9. Adds optional autodoc integration so Sphinx projects can automatically convert docstring Example: / Examples: doctest blocks into interactive py-repl widgets at build time — without duplicating examples into RST or stripping expected outputs from Python source.

Changes

• sphinx_pyrepl_web/doctest.py — extract_doctest_inputs() strips expected output and traceback blocks while preserving >>> / ... input lines (including bare ... terminators)
• sphinx_pyrepl_web/autodoc.py — autodoc-process-docstring hook injects .. py-repl:: directives into matching docstring sections
• sphinx_pyrepl_web/__init__.py — extract register_replay_script() helper; wire autodoc registration; bump version to 0.2.0
• Tests — unit tests for doctest extraction and hook transformation; full Sphinx build integration test with autoclass
• README — autodoc config documentation and v0.2.0 limitations

Config (opt-in, default off)

pyrepl_autodoc = True
pyrepl_autodoc_packages = "naming"
pyrepl_autodoc_sections = ["Example"]
pyrepl_autodoc_options = {"no-banner": True}

Testing

• 26 tests pass (pytest tests/)
• Autodoc hook unit tests (section detection, traceback stripping, directive formatting)
• Full build integration test (autoclass → <py-repl> HTML + replay scripts compile cleanly)
• Existing .. py-repl:: directive behavior unchanged

Limitations (documented)

• Targets raw Google-style / plain-text section headers (no sphinx.ext.napoleon support yet)
• :packages: required (or auto-derived from object name) for Pyodide import
• Live REPL output may differ from doctest expected output (e.g. PosixPath vs WindowsPath)

Downstream

Enables naming to enable autodoc REPLs on Name, File, Pipe, and PipeFile autoclass pages after bumping to sphinx-pyrepl-web>=0.2.0.

  

[read-the-docs-community]

Documentation build overview

📚 sphinx-pyrepl-web | 🛠️ Build #33337019 | 📁 Comparing 08dd88f against latest (bbb8ec8)

  🔍 Preview build  

1 file changed

± index.html

[chrizzFTD]

@cursoragent review

[cursor]

PR Review: #11 — Autodoc integration (v0.2.0)

Verdict: Approve with minor suggestions. The implementation matches issue #9, is opt-in and backward compatible, and the test coverage is solid for the naming downstream case. RTD preview build succeeded.

---

What works well

Architecture — Directive injection via autodoc-process-docstring is the right call. It reuses the existing PyRepl pipeline (replay scripts, metadata, JS loading) without duplicating HTML generation logic.

extract_doctest_inputs() — The traceback state machine correctly handles the tricky ... ellipsis case (only resumes on >>> , not ...). Naming-like fixtures are well covered.

register_replay_script() refactor — Clean extraction from PyRepl.run(); existing directive tests still pass.

Integration test — Full autoclass → HTML → replay script → py_compile path gives good confidence the injected RST parses correctly inside docstrings (the highest-risk part of this feature).

Documentation — README config table and v0.2.0 limitations (Napoleon, packages, live output differences) are accurate and honest.

---

Non-blocking suggestions

1. Private cross-module import

autodoc.py imports _is_doctest_input_line from doctest.py. Consider either making it public (drop the underscore) or inlining a small shared helper to avoid coupling on a private API.

2. Hard-coded what filter

_DEFAULT_WHAT = frozenset({"class", "function", "method"})

Module docstring Example: blocks are skipped. Fine for naming, but worth a one-line note in the README. A future pyrepl_autodoc_what config would make this extensible.

3. Package auto-derivation is untested in integration

Unit test covers derive_packages("naming.Name"), but the build test always sets pyrepl_autodoc_packages explicitly. A small test with pyrepl_autodoc_packages = None would lock in auto-derivation behavior.

4. Section header case sensitivity

_OTHER_SECTION_HEADERS and configured sections are case-sensitive (Example yes, example no). Acceptable for v0.2.0; document if intentional.

5. Git history noise

The branch has commit → revert → reapply. Recommend squash merge to keep main history clean.

6. Pre-existing (not introduced here)

:strip-prompts: is still in option_spec/README but unused — strip_doctest_prompts() always runs.

---

Risks accepted (documented, OK for merge)

Risk	Assessment
No Napoleon support	Documented; naming doesn't use it
Live output ≠ doctest output	By design; documented
derive_packages("pkg.submod.Class") → pkg.submod	May not match PyPI name; explicit config is the safe path
Lost toggleprompt on converted blocks	Expected UX change

---

Test summary

26 passed — unit (doctest extraction, hook transform) + integration (autoclass build) + regression (existing directive)

Missing but not blocking: multiple Example sections in one docstring, auto-derive packages end-to-end, parallel read with autodoc (existing parallel test covers manual directives only).

---

Recommendation

Merge after squash. This unblocks naming to enable:

pyrepl_autodoc = True
pyrepl_autodoc_packages = "naming"
pyrepl_autodoc_sections = ["Example"]
pyrepl_autodoc_options = {"no-banner": True}

No code changes required before merge unless you want to address the private-import or auto-derive test items in this PR.

  

[chrizzFTD]

Implemented in #12