sphinx-pyrepl-web 0.1.0__tar.gz → 0.2.0__tar.gz

{sphinx_pyrepl_web-0.1.0 → sphinx_pyrepl_web-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-pyrepl-web
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Sphinx extension for embedding pyrepl-web Python REPLs in documentation.
 Keywords: sphinx,pyrepl,pyodide,repl
 Author-email: Christian López Barrón <chris.gfz@gmail.com>
@@ -74,30 +74,56 @@ Embed a REPL with the `py-repl` directive:
 
 ### Directive options
 
-Most options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with a few exceptions unique to this extension: 
+All options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with the exception of `silent`: 
 
-| Option | Description | `pyrepl-web` attr? |
-|--------|-------------|------------------|
-| `:theme:` | Color theme (`catppuccin-mocha`, `catppuccin-latte`) | ✅                |
-| `:packages:` | Comma-separated PyPI packages to preload | ✅                |
-| `:repl-title:` | Title in the REPL header | ✅                |
-| `:src:` | Path to a Python startup script | ✅                |
-| `:replay:` | Replay `:src:` with interactive prompts instead of silent load | ✅                |
-| `:silent:` | Keep `:src:` silent even when combined with a directive body | ❌                |
-| `:strip-prompts:` | Strip ``>>>`` / ``...`` prefixes from directive body | ❌                |
-| `:no-header:` | Hide the header bar | ✅                |
-| `:no-buttons:` | Hide copy/clear buttons | ✅                |
-| `:readonly:` | Disable input | ✅                |
-| `:no-banner:` | Hide the Python version banner | ✅                |
+| Option | Description |
+|--------|-------------|
+| `:theme:` | Color theme (`catppuccin-mocha`, `catppuccin-latte`) |
+| `:packages:` | Comma-separated PyPI packages to preload |
+| `:repl-title:` | Title in the REPL header |
+| `:src:` | Path to a Python startup script |
+| `:replay:` | Replay `:src:` with interactive prompts instead of silent load |
+| `:silent:` | Keep `:src:` silent even when combined with a directive body |
+| `:no-header:` | Hide the header bar |
+| `:no-buttons:` | Hide copy/clear buttons |
+| `:readonly:` | Disable input |
+| `:no-banner:` | Hide the Python version banner |
 
-Directive body content (inline Python in the `.. py-repl::` block) is also extension-only: it is written to `_static/pyrepl/` at build time and emitted as `replay-src`.
+Python code within the `.. py-repl::` directive is written to `_static/pyrepl/` at build time and emitted as `replay-src`.
 
 Optional Sphinx config:
 
 ```python
 pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script
+pyrepl_doctest_blocks = False  # default; see Docstring conversion below
+pyrepl_autodoc_bootstrap = True  # default; silent :src: bootstrap for autodoc REPLs
 ```
 
+### Docstring conversion
+
+Converting doctest examples from docstrings into interactive REPLs is opt-in with `sphinx.ext.autodoc`:
+
+```python
+# conf.py
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_pyrepl_web",
+]
+pyrepl_doctest_blocks = "autodoc"
+```
+
+|                   | `pyrepl_doctest_blocks` options     |
+|-------------------|-------------------------------------|
+| `False` (default) | Disable autodoc conversion          |
+| `"autodoc"`       | Convert doctests found by autodoc   |
+| `"all"`           | Transform every doctest block found |
+
+
+|                  | `pyrepl_autodoc_bootstrap` options                                           |
+|------------------|------------------------------------------------------------------------------|
+| `True` (default) | Bootstrap REPL: in-tree modules via silent `:src:`, packages via `packages=` |
+| `False`          | Replay doctest input only; documented names are not pre-defined              |
+
 ## Updating pyrepl-web
 
 Since [chrizzFTD/pyrepl-web](https://github.com/chrizzFTD/pyrepl-web) is a fork, this sphinx extension vendors the JavaScript assets for easier distribution. To update them, run:
@@ -109,7 +135,7 @@ python scripts/vendor_repl.py
 The `grill` branch is used by default. Use the `branch` argument to specify a different one:
 
 ```bash
-python scripts/vendor_repl.py --branch cursor/repl-startup-replay-2e3f
+python scripts/vendor_repl.py --branch custom/feature-branch
 ```
 
 This requires [git](https://git-scm.com/) and [Bun](https://bun.sh/).

sphinx_pyrepl_web-0.2.0/README.md

@@ -0,0 +1,113 @@
+# sphinx-pyrepl-web
+
+Sphinx extension to embed [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web) in documentation.
+
+## Install
+
+```bash
+pip install sphinx-pyrepl-web
+```
+
+For development:
+
+```bash
+pip install -e ".[test,docs]"
+```
+
+## Usage
+
+Add the extension to the target project's `conf.py`:
+
+```python
+extensions = [
+    "sphinx_pyrepl_web",
+]
+```
+
+Embed a REPL with the `py-repl` directive:
+
+```rst
+.. py-repl::
+
+.. py-repl::
+   :theme: catppuccin-latte
+   :no-header:
+
+.. py-repl::
+   :src: setup.py
+   :packages: numpy
+
+.. py-repl::
+   :no-header:
+
+   >>> import math
+   >>> math.sqrt(16)
+```
+
+### Directive options
+
+All options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with the exception of `silent`: 
+
+| Option | Description |
+|--------|-------------|
+| `:theme:` | Color theme (`catppuccin-mocha`, `catppuccin-latte`) |
+| `:packages:` | Comma-separated PyPI packages to preload |
+| `:repl-title:` | Title in the REPL header |
+| `:src:` | Path to a Python startup script |
+| `:replay:` | Replay `:src:` with interactive prompts instead of silent load |
+| `:silent:` | Keep `:src:` silent even when combined with a directive body |
+| `:no-header:` | Hide the header bar |
+| `:no-buttons:` | Hide copy/clear buttons |
+| `:readonly:` | Disable input |
+| `:no-banner:` | Hide the Python version banner |
+
+Python code within the `.. py-repl::` directive is written to `_static/pyrepl/` at build time and emitted as `replay-src`.
+
+Optional Sphinx config:
+
+```python
+pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script
+pyrepl_doctest_blocks = False  # default; see Docstring conversion below
+pyrepl_autodoc_bootstrap = True  # default; silent :src: bootstrap for autodoc REPLs
+```
+
+### Docstring conversion
+
+Converting doctest examples from docstrings into interactive REPLs is opt-in with `sphinx.ext.autodoc`:
+
+```python
+# conf.py
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_pyrepl_web",
+]
+pyrepl_doctest_blocks = "autodoc"
+```
+
+|                   | `pyrepl_doctest_blocks` options     |
+|-------------------|-------------------------------------|
+| `False` (default) | Disable autodoc conversion          |
+| `"autodoc"`       | Convert doctests found by autodoc   |
+| `"all"`           | Transform every doctest block found |
+
+
+|                  | `pyrepl_autodoc_bootstrap` options                                           |
+|------------------|------------------------------------------------------------------------------|
+| `True` (default) | Bootstrap REPL: in-tree modules via silent `:src:`, packages via `packages=` |
+| `False`          | Replay doctest input only; documented names are not pre-defined              |
+
+## Updating pyrepl-web
+
+Since [chrizzFTD/pyrepl-web](https://github.com/chrizzFTD/pyrepl-web) is a fork, this sphinx extension vendors the JavaScript assets for easier distribution. To update them, run:
+
+```bash
+python scripts/vendor_repl.py
+```
+
+The `grill` branch is used by default. Use the `branch` argument to specify a different one:
+
+```bash
+python scripts/vendor_repl.py --branch custom/feature-branch
+```
+
+This requires [git](https://git-scm.com/) and [Bun](https://bun.sh/).

sphinx_pyrepl_web-0.2.0/docs/_static/autodoc_demo.py

@@ -0,0 +1,12 @@
+"""Demo module for autodoc doctest REPL integration."""
+
+def example_generator(n):
+    """Generators yield values useful for iteration.
+
+    Example:
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+
+    """
+    yield from range(n)

{sphinx_pyrepl_web-0.1.0 → sphinx_pyrepl_web-0.2.0}/docs/conf.py

@@ -1,7 +1,11 @@
 from datetime import date
+import sys
+from pathlib import Path
 
 from sphinx_pyrepl_web import __version__
 
+sys.path.insert(0, str(Path(__file__).parent / "_static"))
+
 project = "sphinx-pyrepl-web"
 version = __version__
 author = "Christian López Barrón"
@@ -9,8 +13,11 @@ copyright = f"{date.today().year}, {author}"
 
 extensions = [
     "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
     "sphinx_pyrepl_web",
 ]
+pyrepl_doctest_blocks = "autodoc"
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 html_sidebars = {

{sphinx_pyrepl_web-0.1.0 → sphinx_pyrepl_web-0.2.0}/docs/example.rst

@@ -31,24 +31,27 @@ Startup script
 The ``:src:`` option loads a Python script into the REPL namespace. If the script
 defines a ``setup()`` function, its output is shown when the REPL starts.
 
+Startup script:
+
+.. literalinclude:: _static/setup.py
+   :language: python
+
+RST content:
+
 .. code-block:: rst
 
    .. py-repl::
       :src: _static/setup.py
 
+Rendered result:
+
 .. py-repl::
    :src: _static/setup.py
 
-The startup script:
-
-.. literalinclude:: _static/setup.py
-   :language: python
-
 Replay session
 --------------
 
-Inline directive content is replayed with ``>>>`` prompts, syntax highlighting,
-and live output. Doctest-style ``>>>`` prefixes are stripped automatically.
+Inline directive content should follow Doctest-style (``>>>`` / ``...``) and is used as replay prompts.
 
 .. code-block:: rst
 
@@ -59,6 +62,10 @@ and live output. Doctest-style ``>>>`` prefixes are stripped automatically.
       >>> x = 2 + 2
       >>> print(f"{x=}")
       >>> x * 10
+      >>> class Foo:
+      ...     x = 1
+      ...
+      >>> Foo()
 
 .. py-repl::
    :no-header:
@@ -67,6 +74,10 @@ and live output. Doctest-style ``>>>`` prefixes are stripped automatically.
    >>> x = 2 + 2
    >>> print(f"{x=}")
    >>> x * 10
+   >>> class Foo:
+   ...     x = 1
+   ...
+   >>> Foo()
 
 Combine a silent bootstrap file with a visible replay body:
 
@@ -84,7 +95,14 @@ Combine a silent bootstrap file with a visible replay body:
 
    >>> print(message)
 
-Use ``:replay:`` on ``:src:`` to replay a file with prompts instead of silent load:
+Use ``:replay:`` on ``:src:`` to source a file as replay.
+
+Source script:
+
+.. literalinclude:: _static/replay_demo.py
+   :language: python
+
+RST content:
 
 .. code-block:: rst
 
@@ -94,13 +112,32 @@ Use ``:replay:`` on ``:src:`` to replay a file with prompts instead of silent lo
       :no-header:
       :no-banner:
 
+Rendered result:
+
 .. py-repl::
    :src: _static/replay_demo.py
    :replay:
    :no-header:
    :no-banner:
 
-The replay script:
+Autodoc
+-------
 
-.. literalinclude:: _static/replay_demo.py
+The documented module's source is loaded in advance before replay, so
+module members are available in the REPL namespace. Modules under the Sphinx
+source tree use silent ``:src:``; installed packages use ``packages=``.
+
+Source module:
+
+.. literalinclude:: _static/autodoc_demo.py
    :language: python
+
+RST content:
+
+.. code-block:: rst
+
+   .. autofunction:: autodoc_demo.example_generator
+
+Rendered result:
+
+.. autofunction:: autodoc_demo.example_generator

{sphinx_pyrepl_web-0.1.0 → sphinx_pyrepl_web-0.2.0}/pyproject.toml

@@ -38,3 +38,8 @@ test = [
 docs = [
     "myst-parser",
 ]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore:The mapping interface for autodoc options objects is deprecated:sphinx.deprecation.RemovedInSphinx11Warning",
+]

sphinx_pyrepl_web-0.2.0/sphinx_pyrepl_web/__init__.py

@@ -0,0 +1,316 @@
+"""A Sphinx extension for embedding pyrepl-web Python REPLs in documentation."""
+
+__version__ = "0.2.0"
+
+import importlib
+import inspect
+import json
+from doctest import DocTestParser
+from pathlib import Path
+import sys
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.fileutil import copy_asset_file
+
+PYREPL_DIR = Path(__file__).parent / "pyrepl"
+STARTUP_FILES_KEY = "pyrepl-startup-files"
+REPLAY_FILES_KEY = "pyrepl-replay-files"
+_DOCTEST_PARSER = DocTestParser()
+logger = logging.getLogger(__name__)
+
+
+def setup(app: Sphinx):
+    """Setup the extension."""
+    app.add_config_value("pyrepl_js", "../pyrepl.js", "env")
+    app.add_config_value("pyrepl_doctest_blocks", False, "env")
+    app.add_config_value("pyrepl_autodoc_bootstrap", True, "env")
+    app.add_directive("py-repl", PyRepl)
+    app.connect("doctree-read", doctree_read)
+    app.connect("doctree-read", transform_doctest_blocks)
+    app.connect("html-page-context", add_html_context)
+    app.connect("env-updated", copy_asset_files)
+    return {"version": __version__, "parallel_read_safe": True}
+
+
+def doctest_to_replay_source(text_or_lines: str | list[str]) -> str:
+    """Convert doctest-formatted text into executable replay script source."""
+    text = (
+        "\n".join(text_or_lines)
+        if isinstance(text_or_lines, list)
+        else text_or_lines
+    )
+    examples = _DOCTEST_PARSER.get_examples(text)
+    if not examples:
+        return ""
+    parts = [example.source.rstrip("\n") for example in examples]
+    return "\n\n".join(parts) + "\n"
+
+
+def _next_replay_counter(replay_files: dict[str, str]) -> int:
+    return len(replay_files) + 1
+
+
+def register_autodoc_repl(
+    env,
+    docname: str,
+    replay_text: str,
+) -> str:
+    """Record a replay script in env metadata and return its replay-src path."""
+    replay_files = json.loads(
+        env.metadata[docname].setdefault(REPLAY_FILES_KEY, "{}")
+    )
+    counter = _next_replay_counter(replay_files)
+    replay_name = f"{docname.replace('/', '-')}-{counter}.py"
+    replay_files[replay_name] = replay_text
+    env.metadata[docname][REPLAY_FILES_KEY] = json.dumps(replay_files)
+    return f"_static/pyrepl/{replay_name}"
+
+
+def register_startup_file(env, docname: str, path: Path) -> str:
+    """Track a startup script under srcdir for copying into HTML output."""
+    env.note_dependency(path)
+    rel_src = path.relative_to(Path(env.srcdir)).as_posix()
+    startup_files = json.loads(
+        env.metadata[docname].setdefault(STARTUP_FILES_KEY, "[]")
+    )
+    abs_path = str(path.resolve())
+    if abs_path not in startup_files:
+        startup_files.append(abs_path)
+        env.metadata[docname][STARTUP_FILES_KEY] = json.dumps(startup_files)
+    return rel_src
+
+
+def make_pyrepl_raw(
+    replay_src: str,
+    src: str | None = None,
+    packages: str | None = None,
+) -> nodes.raw:
+    """Build a raw HTML node for an autodoc doctest replay widget."""
+    attrs = ["no-header", "no-banner", f'replay-src="{replay_src}"']
+    if packages:
+        attrs.insert(0, f'packages="{packages}"')
+    if src:
+        attrs.insert(0, f'src="{src}"')
+    attr_str = " ".join(attrs)
+    return nodes.raw("", f"<py-repl {attr_str}></py-repl>\n", format="html")
+
+
+def _find_autodoc_desc(node: nodes.Node) -> addnodes.desc | None:
+    """Return the enclosing autodoc desc node, if any."""
+    current = node.parent
+    while current is not None:
+        if isinstance(current, addnodes.desc):
+            return current
+        current = current.parent
+    return None
+
+
+def _resolve_autodoc_bootstrap(
+    app: Sphinx, env, docname: str, desc: addnodes.desc
+) -> tuple[str | None, str | None]:
+    """Return (startup src path, packages) for autodoc REPLs."""
+    if not app.config.pyrepl_autodoc_bootstrap:
+        return None, None
+
+    sig = desc.next_node(addnodes.desc_signature)
+    if sig is None:
+        return None, None
+
+    module_name = sig.get("module")
+    fullname = sig.get("fullname")
+    if not module_name:
+        return None, None
+
+    target = f"{module_name}.{fullname}" if fullname else module_name
+    try:
+        mod = sys.modules.get(module_name)
+        if mod is None:
+            mod = importlib.import_module(module_name)
+        obj = mod
+        if fullname:
+            for part in fullname.split("."):
+                obj = getattr(obj, part)
+        mod_obj = inspect.getmodule(obj) or mod
+        source_path = Path(inspect.getfile(mod_obj)).resolve()
+        srcdir = Path(env.srcdir).resolve()
+        try:
+            source_path.relative_to(srcdir)
+            return register_startup_file(env, docname, source_path), None
+        except ValueError:
+            return None, module_name.split(".")[0]
+    except (AttributeError, ImportError, OSError, TypeError) as exc:
+        logger.error(
+            "Could not bootstrap autodoc REPL for %s: %s",
+            target,
+            exc,
+        )
+        return None, None
+
+
+def _inside_autodoc_desc(node: nodes.Node) -> bool:
+    """Return True if *node* is nested inside an autodoc desc entry."""
+    return _find_autodoc_desc(node) is not None
+
+
+def transform_doctest_blocks(app: Sphinx, doctree: nodes.document):
+    """Replace doctest blocks with interactive py-repl widgets."""
+    scope = app.config.pyrepl_doctest_blocks
+    if not scope:
+        return
+
+    env = app.env
+    docname = env.docname
+    replaced = False
+    for node in doctree.findall(nodes.doctest_block):
+        if scope == "autodoc" and not _inside_autodoc_desc(node):
+            continue
+        source = doctest_to_replay_source(node.astext())
+        if not source.strip():
+            continue
+        bootstrap_src = None
+        packages = None
+        desc = _find_autodoc_desc(node)
+        if desc is not None:
+            bootstrap_src, packages = _resolve_autodoc_bootstrap(
+                app, env, docname, desc
+            )
+        replay_src = register_autodoc_repl(env, docname, source)
+        node.replace_self(make_pyrepl_raw(replay_src, bootstrap_src, packages))
+        replaced = True
+
+    if replaced:
+        env.metadata[docname]["pyrepl"] = True
+        doctree["pyrepl"] = True
+
+
+class PyRepl(SphinxDirective):
+    """Embed a pyrepl-web ``<py-repl>`` element."""
+
+    has_content = True
+    option_spec = {
+        "theme": directives.unchanged,
+        "packages": directives.unchanged,
+        "repl-title": directives.unchanged,
+        "src": directives.path,
+        "no-header": directives.flag,
+        "no-buttons": directives.flag,
+        "readonly": directives.flag,
+        "no-banner": directives.flag,
+        "replay": directives.flag,
+        "silent": directives.flag,
+    }
+
+    def run(self):
+        env = self.env
+        attrs: list[str] = []
+
+        for option, attr in (
+            ("theme", "theme"),
+            ("packages", "packages"),
+            ("repl-title", "repl-title"),
+        ):
+            if option in self.options:
+                value = self.options[option]
+                attrs.append(f'{attr}="{value}"')
+
+        for flag in ("no-header", "no-buttons", "readonly", "no-banner"):
+            if flag in self.options:
+                attrs.append(flag)
+
+        has_body = bool(self.content)
+        force_replay = "replay" in self.options
+        force_silent = "silent" in self.options
+
+        if "src" in self.options:
+            _, abs_path = self.env.relfn2path(self.options["src"])
+            path = Path(abs_path)
+            try:
+                path.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise self.error(f"Could not read file: {exc}") from exc
+            self.env.note_dependency(path)
+            rel_src = path.relative_to(Path(self.env.srcdir)).as_posix()
+            startup_files = json.loads(
+                self.env.metadata[self.env.docname].setdefault(
+                    STARTUP_FILES_KEY, "[]"
+                )
+            )
+            startup_files.append(str(path))
+            self.env.metadata[self.env.docname][STARTUP_FILES_KEY] = json.dumps(
+                startup_files
+            )
+
+            if force_replay and not has_body:
+                attrs.append(f'src="{rel_src}"')
+                attrs.append("replay")
+            elif not (force_silent and not has_body):
+                attrs.append(f'src="{rel_src}"')
+
+        if has_body:
+            body_text = doctest_to_replay_source(list(self.content))
+            replay_src = register_autodoc_repl(env, env.docname, body_text)
+            attrs.append(f'replay-src="{replay_src}"')
+
+        self.env.metadata[self.env.docname]["pyrepl"] = True
+        attr_str = (" " + " ".join(attrs)) if attrs else ""
+        return [nodes.raw("", f"<py-repl{attr_str}></py-repl>\n", format="html")]
+
+
+def doctree_read(app: Sphinx, doctree: nodes.document):
+    """Mark pages that use the py-repl directive."""
+    if app.env.metadata[app.env.docname].get("pyrepl"):
+        doctree["pyrepl"] = True
+
+
+def add_html_context(
+    app: Sphinx, pagename: str, templatename: str, context, doctree: nodes.document
+):
+    """Load pyrepl-web JavaScript on pages that contain a REPL."""
+    if doctree and "pyrepl" in doctree:
+        app.add_js_file(app.config.pyrepl_js)
+
+
+def copy_asset_files(app, _):
+    """Copy vendored pyrepl assets and startup scripts into HTML output."""
+    if app.builder.format != "html":
+        return
+
+    outdir = Path(app.builder.outdir)
+    if PYREPL_DIR.is_dir():
+        for asset in PYREPL_DIR.iterdir():
+            if asset.is_file():
+                copy_asset_file(str(asset.resolve()), str(outdir.resolve()))
+
+    replay_dest = outdir / "_static" / "pyrepl"
+    for docname, metadata in app.env.metadata.items():
+        raw = metadata.get(REPLAY_FILES_KEY)
+        if not raw:
+            continue
+        replay_files = json.loads(raw)
+        if not replay_files:
+            continue
+        replay_dest.mkdir(parents=True, exist_ok=True)
+        for name, content in replay_files.items():
+            (replay_dest / name).write_text(content, encoding="utf-8")
+
+    srcdir = Path(app.builder.srcdir)
+    copied = set()
+    for docname, metadata in app.env.metadata.items():
+        raw = metadata.get(STARTUP_FILES_KEY)
+        if not raw:
+            continue
+        for abs_path in json.loads(raw):
+            path = Path(abs_path)
+            key = str(path.resolve())
+            if key in copied:
+                continue
+            copied.add(key)
+            rel = path.relative_to(srcdir)
+            dest = outdir / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            copy_asset_file(str(path.resolve()), str(dest.resolve()))