sphinx-pyxel

A Sphinx extension that embeds Pyxel apps directly in your HTML documentation using the official Pyxel web runtime.

Install

pip install sphinx-pyxel

Or from source:

pip install .

Usage

Add the extension to your conf.py:

extensions = ["sphinx_pyxel"]

Then use the pyxel directive in any reStructuredText document:

.. pyxel:: examples/01_hello_pyxel.py

For a packaged app (.pyxapp) with gamepad support:

.. pyxel:: examples/30sec_of_daylight.pyxapp
   :mode: play
   :gamepad: enabled

If your app loads external resources, copy them next to it:

.. pyxel:: my_game.py
   :assets: my_game.pyxres, my_game_bank.json

Options

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.

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