sphinx-pyxel 0.1.0__tar.gz

sphinx_pyxel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sphinx-pyxel contributors
+
+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_pyxel-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: sphinx-pyxel
+Version: 0.1.0
+Summary: Sphinx extension to embed Pyxel apps in HTML docs
+Author: sphinx-pyxel
+License: MIT
+Project-URL: Homepage, https://github.com/tetsuokoyama/sphinx-pyxel
+Keywords: sphinx,pyxel,extension,sphinx-extension
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Sphinx>=5
+Dynamic: license-file
+
+# sphinx-pyxel
+
+A [Sphinx](https://www.sphinx-doc.org/) extension that embeds [Pyxel](https://github.com/kitao/pyxel) apps directly in your HTML documentation using the official Pyxel web runtime.
+
+## Install
+
+```bash
+pip install sphinx-pyxel
+```
+
+Or from source:
+
+```bash
+pip install .
+```
+
+## Usage
+
+Add the extension to your `conf.py`:
+
+```python
+extensions = ["sphinx_pyxel"]
+```
+
+Then use the `pyxel` directive in any reStructuredText document:
+
+```rst
+.. pyxel:: examples/01_hello_pyxel.py
+```
+
+For a packaged app (`.pyxapp`) with gamepad support:
+
+```rst
+.. pyxel:: examples/30sec_of_daylight.pyxapp
+   :mode: play
+   :gamepad: enabled
+```
+
+If your app loads external resources, copy them next to it:
+
+```rst
+.. pyxel:: my_game.py
+   :assets: my_game.pyxres, my_game_bank.json
+```
+
+## Options
+
+| Option     | Default                              | Description                                                       |
+|------------|--------------------------------------|-------------------------------------------------------------------|
+| `mode`     | `run` for `.py`, `play` for `.pyxapp`| `run` (just runs) or `play` (player controls, gamepad support).   |
+| `root`     | `.` (or rel path to `pyxel_root`)    | Root path served relative to the HTML page.                       |
+| `name`     | basename of the argument             | File name served by the runtime.                                  |
+| `gamepad`  | unset                                | `enabled` or `disabled` (only meaningful for `play`).            |
+| `assets`   | unset                                | Comma-separated extra files to copy next to the app.              |
+| `script`   | jsdelivr wasm build                  | URL of the Pyxel web runtime script.                              |
+| `height`   | `480px`                              | CSS height of the inline app window.                              |
+
+## How it works
+
+During the build, the directive copies the referenced app file (and any
+`assets`) into the output directory next to the generated HTML page, then emits
+a `<pyxel-run>` (or `<pyxel-play>`) custom element plus the Pyxel web runtime
+script tag. The app runs entirely in the browser — no Python is executed by
+Sphinx.
+
+The app renders **inline** at the location of the directive (not fullscreen):
+the extension places a ``#pyxel-screen`` container there and overrides the
+runtime's fullscreen CSS so the canvas fills that container. Set ``:height:``
+to control the window size.
+
+## Config value: `pyxel_root`
+
+Set ``pyxel_root`` in ``conf.py`` to collect every app into one shared
+directory under the HTML output instead of copying it next to each page that
+references it. Each emitted ``root`` then points from the page back at the
+shared directory, so an app reused across many pages is stored once.
+
+```python
+pyxel_root = "_pyxel"
+```
+
+## Limitations
+
+- The embedded app only renders in the **HTML** builder. Other builders (LaTeX,
+  man, text, etc.) emit a short note instead. This is expected: the Pyxel web
+  runtime is JavaScript and only runs in a browser.
+- One file is copied next to each page that references it **unless**
+  ``pyxel_root`` is set, in which case apps are collected into one shared
+  directory. Two apps with the same basename under ``pyxel_root`` would
+  collide; give one a distinct ``:name:`` if that happens.
+
+## License
+
+MIT

sphinx_pyxel-0.1.0/README.md

@@ -0,0 +1,94 @@
+# sphinx-pyxel
+
+A [Sphinx](https://www.sphinx-doc.org/) extension that embeds [Pyxel](https://github.com/kitao/pyxel) apps directly in your HTML documentation using the official Pyxel web runtime.
+
+## Install
+
+```bash
+pip install sphinx-pyxel
+```
+
+Or from source:
+
+```bash
+pip install .
+```
+
+## Usage
+
+Add the extension to your `conf.py`:
+
+```python
+extensions = ["sphinx_pyxel"]
+```
+
+Then use the `pyxel` directive in any reStructuredText document:
+
+```rst
+.. pyxel:: examples/01_hello_pyxel.py
+```
+
+For a packaged app (`.pyxapp`) with gamepad support:
+
+```rst
+.. pyxel:: examples/30sec_of_daylight.pyxapp
+   :mode: play
+   :gamepad: enabled
+```
+
+If your app loads external resources, copy them next to it:
+
+```rst
+.. pyxel:: my_game.py
+   :assets: my_game.pyxres, my_game_bank.json
+```
+
+## Options
+
+| Option     | Default                              | Description                                                       |
+|------------|--------------------------------------|-------------------------------------------------------------------|
+| `mode`     | `run` for `.py`, `play` for `.pyxapp`| `run` (just runs) or `play` (player controls, gamepad support).   |
+| `root`     | `.` (or rel path to `pyxel_root`)    | Root path served relative to the HTML page.                       |
+| `name`     | basename of the argument             | File name served by the runtime.                                  |
+| `gamepad`  | unset                                | `enabled` or `disabled` (only meaningful for `play`).            |
+| `assets`   | unset                                | Comma-separated extra files to copy next to the app.              |
+| `script`   | jsdelivr wasm build                  | URL of the Pyxel web runtime script.                              |
+| `height`   | `480px`                              | CSS height of the inline app window.                              |
+
+## How it works
+
+During the build, the directive copies the referenced app file (and any
+`assets`) into the output directory next to the generated HTML page, then emits
+a `<pyxel-run>` (or `<pyxel-play>`) custom element plus the Pyxel web runtime
+script tag. The app runs entirely in the browser — no Python is executed by
+Sphinx.
+
+The app renders **inline** at the location of the directive (not fullscreen):
+the extension places a ``#pyxel-screen`` container there and overrides the
+runtime's fullscreen CSS so the canvas fills that container. Set ``:height:``
+to control the window size.
+
+## Config value: `pyxel_root`
+
+Set ``pyxel_root`` in ``conf.py`` to collect every app into one shared
+directory under the HTML output instead of copying it next to each page that
+references it. Each emitted ``root`` then points from the page back at the
+shared directory, so an app reused across many pages is stored once.
+
+```python
+pyxel_root = "_pyxel"
+```
+
+## Limitations
+
+- The embedded app only renders in the **HTML** builder. Other builders (LaTeX,
+  man, text, etc.) emit a short note instead. This is expected: the Pyxel web
+  runtime is JavaScript and only runs in a browser.
+- One file is copied next to each page that references it **unless**
+  ``pyxel_root`` is set, in which case apps are collected into one shared
+  directory. Two apps with the same basename under ``pyxel_root`` would
+  collide; give one a distinct ``:name:`` if that happens.
+
+## License
+
+MIT

sphinx_pyxel-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinx-pyxel"
+version = "0.1.0"
+description = "Sphinx extension to embed Pyxel apps in HTML docs"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "sphinx-pyxel"}]
+requires-python = ">=3.8"
+dependencies = ["Sphinx>=5"]
+keywords = ["sphinx", "pyxel", "extension", "sphinx-extension"]
+classifiers = [
+    "Framework :: Sphinx :: Extension",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/tetsuokoyama/sphinx-pyxel"
+
+[tool.setuptools.packages.find]
+include = ["sphinx_pyxel*"]

sphinx_pyxel-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sphinx_pyxel-0.1.0/sphinx_pyxel/__init__.py

@@ -0,0 +1,203 @@
+"""Sphinx extension to embed Pyxel apps in HTML documentation.
+
+Provides the ``pyxel`` directive, which copies a Pyxel app (a ``.py`` file or a
+packaged ``.pyxapp``) into the build output and renders it with the official
+Pyxel web runtime::
+
+    .. pyxel:: examples/01_hello_pyxel.py
+
+    .. pyxel:: examples/30sec_of_daylight.pyxapp
+       :mode: play
+       :gamepad: enabled
+
+Options:
+    :mode: run | play  (auto-detected from extension; ``run`` for .py,
+                       ``play`` for .pyxapp)
+    :root:  root path served relative to the HTML page (default: copied
+            next to the page, so root is "."; when ``pyxel_root`` is set,
+            default is the relative path from the page to the shared dir)
+    :name:  file name served (default: basename of the argument)
+    :gamepad: enabled | disabled (only meaningful for ``play``)
+    :assets: comma-separated extra files to copy next to the app
+            (e.g. ``mygame.pyxres``)
+    :script: URL of the Pyxel web runtime (default: the jsdelivr wasm build)
+
+Config value:
+    pyxel_root  -- directory under the HTML output where apps are collected
+                   (e.g. ``_pyxel``). When set, each app is copied there once
+                   instead of next to every page that references it, and the
+                   emitted ``root`` points back at it from each page. Default:
+                   unset (copy next to the page).
+
+Only the HTML builder embeds the runtime; other builders emit a note pointing
+at the app file name.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util import logging
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_SCRIPT = "https://cdn.jsdelivr.net/gh/kitao/pyxel/wasm/pyxel.js"
+
+
+class PyxelDirective(SphinxDirective):
+    """Embed a Pyxel app via the web runtime."""
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        "mode": str,
+        "root": str,
+        "name": str,
+        "gamepad": str,
+        "assets": str,
+        "script": str,
+        "height": str,
+    }
+
+    def run(self):
+        rel_src, abs_src = self.env.relfn2path(self.arguments[0].strip())
+        self.env.note_dependency(rel_src)
+
+        if not os.path.isfile(abs_src):
+            logger.warning("pyxel: file not found: %s", abs_src, location=self.get_source_info())
+            return [self.state.document.reporter.warning(
+                "pyxel: file not found: %s" % self.arguments[0], line=self.lineno)]
+
+        basename = os.path.basename(abs_src)
+        ext = os.path.splitext(basename)[1].lower()
+
+        mode = self.options.get("mode")
+        if mode is None:
+            mode = "play" if ext == ".pyxapp" else "run"
+        if mode not in ("run", "play"):
+            logger.warning("pyxel: :mode: must be 'run' or 'play', got %r", mode,
+                           location=self.get_source_info())
+            mode = "play" if ext == ".pyxapp" else "run"
+
+        page_dir = self._page_dir()
+        pyxel_root = self.env.config.pyxel_root
+        if pyxel_root:
+            # Collect apps into one shared dir under the output; emit a root
+            # relative to the page so the runtime can fetch them.
+            shared_dir = os.path.join(self.env.app.builder.outdir, pyxel_root)
+            os.makedirs(shared_dir, exist_ok=True)
+            dest = os.path.join(shared_dir, basename)
+            shutil.copyfile(abs_src, dest)
+            default_root = os.path.relpath(shared_dir, page_dir).replace(os.sep, "/")
+            asset_dir = shared_dir
+        else:
+            # Copy the app next to the generated HTML page so the runtime can
+            # fetch it with a relative path.
+            os.makedirs(page_dir, exist_ok=True)
+            dest = os.path.join(page_dir, basename)
+            shutil.copyfile(abs_src, dest)
+            default_root = "."
+            asset_dir = page_dir
+
+        assets = [a.strip() for a in (self.options.get("assets") or "").split(",") if a.strip()]
+        for asset in assets:
+            a_rel, a_abs = self.env.relfn2path(asset)
+            self.env.note_dependency(a_rel)
+            if os.path.isfile(a_abs):
+                shutil.copyfile(a_abs, os.path.join(asset_dir, os.path.basename(a_abs)))
+            else:
+                logger.warning("pyxel: asset not found: %s", a_abs, location=self.get_source_info())
+
+        root = self.options.get("root", default_root)
+        name = self.options.get("name", basename)
+        script = self.options.get("script", DEFAULT_SCRIPT)
+
+        attrs = f'\n      root="{root}"\n      name="{name}"'
+        if mode == "play" and self.options.get("gamepad"):
+            attrs += f'\n      gamepad="{self.options["gamepad"]}"'
+
+        tag = "pyxel-" + mode
+        # Emit the runtime <script> once per page per URL: the Pyxel runtime
+        # declares module-level consts, so loading it twice redeclares them and
+        # throws "Identifier 'PYODIDE_URL' has already been declared".
+        if not hasattr(self.env, "_pyxel_scripts"):
+            self.env._pyxel_scripts = {}
+        emitted = self.env._pyxel_scripts.setdefault(self.env.docname, set())
+        script_tag = "" if script in emitted else f'<script src="{script}"></script>'
+        emitted.add(script)
+
+        # Emit <div id="pyxel-screen"> once per page. The runtime's
+        # _createScreenElements does querySelector("div#pyxel-screen") first and
+        # only creates+appends-to-body if none exists, so placing it here makes
+        # the app render inline at the directive's location instead of taking
+        # over the whole page. The runtime only supports one screen per page,
+        # so a second directive on the same page reuses this div.
+        if not hasattr(self.env, "_pyxel_screens"):
+            self.env._pyxel_screens = set()
+        screen_div = "" if self.env.docname in self.env._pyxel_screens else '<div id="pyxel-screen"></div>'
+        self.env._pyxel_screens.add(self.env.docname)
+
+        # The runtime's own pyxel.css forces #pyxel-screen fullscreen. Override
+        # with higher specificity (.pyxel-app div#pyxel-screen) so it sizes to
+        # the container instead. Cascade order doesn't matter: specificity wins.
+        height = self.options.get("height", "480px")
+        style = (
+            '<style>'
+            '.pyxel-app{position:relative;width:100%;}'
+            f'.pyxel-app div#pyxel-screen{{position:relative;left:auto;top:auto;'
+            f'width:100%;height:{height};background-color:#202224;}}'
+            '.pyxel-app div#pyxel-screen canvas#canvas{position:relative;'
+            'left:auto;top:auto;width:100%;height:100%;}'
+            '</style>'
+        )
+
+        html = (
+            f'<div class="pyxel-app">'
+            f'{style}'
+            f'{screen_div}'
+            f'{script_tag}'
+            f'<{tag}{attrs}\n    ></{tag}>'
+            f'</div>'
+        )
+
+        container = nodes.container(classes=["pyxel"])
+        container += nodes.raw("", html, format="html")
+        # Fallback for non-HTML builders.
+        container += nodes.paragraph(
+            "", f"Pyxel app ({mode}): {name}. "
+            "View this page in the HTML build to play it."
+        )
+        return [container]
+
+    def _page_dir(self):
+        outdir = self.env.app.builder.outdir
+        outname = self.env.app.builder.get_outfilename(self.env.docname)
+        return os.path.dirname(outname) or outdir
+
+
+def _purge_doc(app, env, docname):
+    scripts = getattr(env, "_pyxel_scripts", None)
+    if scripts:
+        scripts.pop(docname, None)
+    screens = getattr(env, "_pyxel_screens", None)
+    if screens:
+        screens.discard(docname)
+
+
+def setup(app):
+    app.add_directive("pyxel", PyxelDirective)
+    app.add_node(nodes.container, override=True)
+    app.add_config_value("pyxel_root", None, "html")
+    app.connect("env-purge-doc", _purge_doc)
+    return {
+        "version": __version__,
+        "parallel_read_safe": False,  # we copy files during read
+        "parallel_write_safe": True,
+    }

sphinx_pyxel-0.1.0/sphinx_pyxel.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: sphinx-pyxel
+Version: 0.1.0
+Summary: Sphinx extension to embed Pyxel apps in HTML docs
+Author: sphinx-pyxel
+License: MIT
+Project-URL: Homepage, https://github.com/tetsuokoyama/sphinx-pyxel
+Keywords: sphinx,pyxel,extension,sphinx-extension
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Sphinx>=5
+Dynamic: license-file
+
+# sphinx-pyxel
+
+A [Sphinx](https://www.sphinx-doc.org/) extension that embeds [Pyxel](https://github.com/kitao/pyxel) apps directly in your HTML documentation using the official Pyxel web runtime.
+
+## Install
+
+```bash
+pip install sphinx-pyxel
+```
+
+Or from source:
+
+```bash
+pip install .
+```
+
+## Usage
+
+Add the extension to your `conf.py`:
+
+```python
+extensions = ["sphinx_pyxel"]
+```
+
+Then use the `pyxel` directive in any reStructuredText document:
+
+```rst
+.. pyxel:: examples/01_hello_pyxel.py
+```
+
+For a packaged app (`.pyxapp`) with gamepad support:
+
+```rst
+.. pyxel:: examples/30sec_of_daylight.pyxapp
+   :mode: play
+   :gamepad: enabled
+```
+
+If your app loads external resources, copy them next to it:
+
+```rst
+.. pyxel:: my_game.py
+   :assets: my_game.pyxres, my_game_bank.json
+```
+
+## Options
+
+| Option     | Default                              | Description                                                       |
+|------------|--------------------------------------|-------------------------------------------------------------------|
+| `mode`     | `run` for `.py`, `play` for `.pyxapp`| `run` (just runs) or `play` (player controls, gamepad support).   |
+| `root`     | `.` (or rel path to `pyxel_root`)    | Root path served relative to the HTML page.                       |
+| `name`     | basename of the argument             | File name served by the runtime.                                  |
+| `gamepad`  | unset                                | `enabled` or `disabled` (only meaningful for `play`).            |
+| `assets`   | unset                                | Comma-separated extra files to copy next to the app.              |
+| `script`   | jsdelivr wasm build                  | URL of the Pyxel web runtime script.                              |
+| `height`   | `480px`                              | CSS height of the inline app window.                              |
+
+## How it works
+
+During the build, the directive copies the referenced app file (and any
+`assets`) into the output directory next to the generated HTML page, then emits
+a `<pyxel-run>` (or `<pyxel-play>`) custom element plus the Pyxel web runtime
+script tag. The app runs entirely in the browser — no Python is executed by
+Sphinx.
+
+The app renders **inline** at the location of the directive (not fullscreen):
+the extension places a ``#pyxel-screen`` container there and overrides the
+runtime's fullscreen CSS so the canvas fills that container. Set ``:height:``
+to control the window size.
+
+## Config value: `pyxel_root`
+
+Set ``pyxel_root`` in ``conf.py`` to collect every app into one shared
+directory under the HTML output instead of copying it next to each page that
+references it. Each emitted ``root`` then points from the page back at the
+shared directory, so an app reused across many pages is stored once.
+
+```python
+pyxel_root = "_pyxel"
+```
+
+## Limitations
+
+- The embedded app only renders in the **HTML** builder. Other builders (LaTeX,
+  man, text, etc.) emit a short note instead. This is expected: the Pyxel web
+  runtime is JavaScript and only runs in a browser.
+- One file is copied next to each page that references it **unless**
+  ``pyxel_root`` is set, in which case apps are collected into one shared
+  directory. Two apps with the same basename under ``pyxel_root`` would
+  collide; give one a distinct ``:name:`` if that happens.
+
+## License
+
+MIT

sphinx_pyxel-0.1.0/sphinx_pyxel.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+sphinx_pyxel/__init__.py
+sphinx_pyxel.egg-info/PKG-INFO
+sphinx_pyxel.egg-info/SOURCES.txt
+sphinx_pyxel.egg-info/dependency_links.txt
+sphinx_pyxel.egg-info/requires.txt
+sphinx_pyxel.egg-info/top_level.txt

sphinx_pyxel-0.1.0/sphinx_pyxel.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sphinx_pyxel-0.1.0/sphinx_pyxel.egg-info/requires.txt

@@ -0,0 +1 @@
+Sphinx>=5

sphinx_pyxel-0.1.0/sphinx_pyxel.egg-info/top_level.txt

@@ -0,0 +1 @@
+sphinx_pyxel