sphinx-pyrepl-web 0.1.0__tar.gz

sphinx_pyrepl_web-0.1.0/.github/workflows/python-package.yml

@@ -0,0 +1,31 @@
+# Run tests on push.
+# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python CI
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[test]"
+          python -m pip install pytest-cov codecov
+      - name: Test
+        run: |
+          PYTHONWARNINGS=error pytest --cov --durations=10 .
+        # https://github.com/marketplace/actions/codecov
+      - name: Codecov Report
+        if: matrix.python-version == '3.14'
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

sphinx_pyrepl_web-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv-build-test/
+.venv-testpypi/
+docs/_build/
+dist/
+build/
+*.egg

sphinx_pyrepl_web-0.1.0/.readthedocs.yml

@@ -0,0 +1,15 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+   configuration: docs/conf.py

sphinx_pyrepl_web-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian López Barrón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_pyrepl_web-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: sphinx-pyrepl-web
+Version: 0.1.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>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+License-File: LICENSE
+Requires-Dist: sphinx>9
+Requires-Dist: myst-parser ; extra == "docs"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: sphinx-pytest ; extra == "test"
+Project-URL: Documentation, https://sphinx-pyrepl-web.readthedocs.io/
+Project-URL: Home, https://github.com/chrizzFTD/sphinx-pyrepl-web
+Project-URL: Issues, https://github.com/chrizzFTD/sphinx-pyrepl-web/issues
+Project-URL: Repository, https://github.com/chrizzFTD/sphinx-pyrepl-web
+Provides-Extra: docs
+Provides-Extra: test
+
+# 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
+
+Most options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with a few exceptions unique to this extension: 
+
+| 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 | ✅                |
+
+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`.
+
+Optional Sphinx config:
+
+```python
+pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script
+```
+
+## 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 cursor/repl-startup-replay-2e3f
+```
+
+This requires [git](https://git-scm.com/) and [Bun](https://bun.sh/).
+

sphinx_pyrepl_web-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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
+
+Most options drive [pyrepl-web](https://github.com/chrizzFTD/pyrepl-web)'s attributes, with a few exceptions unique to this extension: 
+
+| 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 | ✅                |
+
+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`.
+
+Optional Sphinx config:
+
+```python
+pyrepl_js = "../pyrepl.js"  # default; path to the pyrepl-web loader script
+```
+
+## 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 cursor/repl-startup-replay-2e3f
+```
+
+This requires [git](https://git-scm.com/) and [Bun](https://bun.sh/).

sphinx_pyrepl_web-0.1.0/docs/_static/replay_demo.py

@@ -0,0 +1,3 @@
+greeting = "Hello from replay mode"
+print(greeting)
+greeting.upper()

sphinx_pyrepl_web-0.1.0/docs/_static/setup.py

@@ -0,0 +1,6 @@
+message = "Hello from the startup script!"
+
+
+def setup():
+    print(message)
+    print("Try: message")

sphinx_pyrepl_web-0.1.0/docs/conf.py

@@ -0,0 +1,21 @@
+from datetime import date
+
+from sphinx_pyrepl_web import __version__
+
+project = "sphinx-pyrepl-web"
+version = __version__
+author = "Christian López Barrón"
+copyright = f"{date.today().year}, {author}"
+
+extensions = [
+    "myst_parser",
+    "sphinx_pyrepl_web",
+]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_sidebars = {
+    "**": [
+        "about.html",
+        "localtoc.html",
+    ],
+}

sphinx_pyrepl_web-0.1.0/docs/example.rst

@@ -0,0 +1,106 @@
+Examples
+========
+
+Basic REPL
+----------
+
+.. code-block:: rst
+
+   .. py-repl::
+
+.. py-repl::
+
+Light theme, minimal
+--------------------
+
+.. code-block:: rst
+
+   .. py-repl::
+      :theme: catppuccin-latte
+      :no-header:
+      :no-banner:
+
+.. py-repl::
+   :theme: catppuccin-latte
+   :no-header:
+   :no-banner:
+
+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.
+
+.. code-block:: rst
+
+   .. py-repl::
+      :src: _static/setup.py
+
+.. 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.
+
+.. code-block:: rst
+
+   .. py-repl::
+      :no-header:
+      :no-banner:
+
+      >>> x = 2 + 2
+      >>> print(f"{x=}")
+      >>> x * 10
+
+.. py-repl::
+   :no-header:
+   :no-banner:
+
+   >>> x = 2 + 2
+   >>> print(f"{x=}")
+   >>> x * 10
+
+Combine a silent bootstrap file with a visible replay body:
+
+.. code-block:: rst
+
+   .. py-repl::
+      :src: _static/setup.py
+      :no-header:
+
+      >>> print(message)
+
+.. py-repl::
+   :src: _static/setup.py
+   :no-header:
+
+   >>> print(message)
+
+Use ``:replay:`` on ``:src:`` to replay a file with prompts instead of silent load:
+
+.. code-block:: rst
+
+   .. py-repl::
+      :src: _static/replay_demo.py
+      :replay:
+      :no-header:
+      :no-banner:
+
+.. py-repl::
+   :src: _static/replay_demo.py
+   :replay:
+   :no-header:
+   :no-banner:
+
+The replay script:
+
+.. literalinclude:: _static/replay_demo.py
+   :language: python

sphinx_pyrepl_web-0.1.0/docs/index.rst

@@ -0,0 +1,7 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. include:: example.rst
+
+.. toctree::
+   :maxdepth: 2

sphinx_pyrepl_web-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "sphinx-pyrepl-web"
+authors = [{name = "Christian López Barrón", email = "chris.gfz@gmail.com"}]
+readme = "README.md"
+license = {file = "LICENSE"}
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Sphinx :: Extension",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+]
+keywords = ["sphinx", "pyrepl", "pyodide", "repl"]
+dynamic = ["version", "description"]
+requires-python = ">=3.12"
+dependencies = [
+    "sphinx>9",
+]
+
+[project.urls]
+Home = "https://github.com/chrizzFTD/sphinx-pyrepl-web"
+Documentation = "https://sphinx-pyrepl-web.readthedocs.io/"
+Repository = "https://github.com/chrizzFTD/sphinx-pyrepl-web"
+Issues = "https://github.com/chrizzFTD/sphinx-pyrepl-web/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "sphinx-pytest",
+]
+docs = [
+    "myst-parser",
+]

sphinx_pyrepl_web-0.1.0/scripts/vendor_repl.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Vendor pyrepl-web build artifacts from chrizzFTD/pyrepl-web (grill branch)."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+REPO = "https://github.com/chrizzFTD/pyrepl-web.git"
+DEFAULT_BRANCH = "grill"
+
+
+def run(cmd: list[str], *, cwd: Path | None = None) -> None:
+    print(f"+ {' '.join(cmd)}")
+    subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def require_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        sys.exit(f"error: {name!r} not found on PATH")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--asset-dir",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent / "sphinx_pyrepl_web" / "pyrepl",
+        help="Directory to write vendored assets into",
+    )
+    parser.add_argument(
+        "--branch",
+        default=DEFAULT_BRANCH,
+        help=f"pyrepl-web branch to vendor (default: {DEFAULT_BRANCH})",
+    )
+    args = parser.parse_args()
+    asset_dir: Path = args.asset_dir
+    branch: str = args.branch
+
+    require_tool("git")
+    require_tool("bun")
+
+    with tempfile.TemporaryDirectory(prefix="vendor-pyrepl-") as tmp:
+        clone_dir = Path(tmp) / "pyrepl-web"
+        run(
+            [
+                "git",
+                "clone",
+                "--depth",
+                "1",
+                "--branch",
+                branch,
+                REPO,
+                str(clone_dir),
+            ]
+        )
+        commit = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=clone_dir,
+            text=True,
+        ).strip()
+        run(["bun", "install"], cwd=clone_dir)
+        run(["bun", "run", "build"], cwd=clone_dir)
+
+        dist = clone_dir / "dist"
+        if not dist.is_dir():
+            sys.exit(f"error: build did not produce {dist}")
+
+        if asset_dir.exists():
+            shutil.rmtree(asset_dir)
+        asset_dir.mkdir(parents=True)
+        copied = []
+        for src in sorted(dist.iterdir()):
+            if src.is_file():
+                shutil.copy2(src, asset_dir / src.name)
+                copied.append(src.name)
+
+        version_file = asset_dir / "version.txt"
+        version_file.write_text(f"{branch}@{commit}\n", encoding="utf-8")
+        copied.append("version.txt")
+
+    print(f"\nVendored {len(copied)} file(s) to {asset_dir}:")
+    for name in copied:
+        print(f"  {name}")
+    print(f"Source: {REPO} ({branch}@{commit})")
+
+
+if __name__ == "__main__":
+    main()