# sphinx-nostalgistjs
Sphinx extension for embedding RetroArch in HTML documents, using [NostalgistJS](https://nostalgist.js.org/).
Styling and layout depend on Bootstrap v5, not included.
This package is released on [pypi](https://pypi.org/project/sphinx-nostalgistjs/).
<!--ENGBR_SECTION
## Demo
Click to start. Use the Z key to jump, and the Enter key to start.
This is emulating "flappybird.nes" on the "FCEUmm" core in RetroArch.
```{nostalgistjs}
:rom_url: "flappybird.nes"
:core_id: fceumm
{
"omit_attribution": true
}
```
ENGBR_SECTION-->
## Basic Usage
Add this extension to your Sphinx `conf.py`, like so:
``` python
extensions = [
"sphinx_nostalgistjs",
⋯
]
```
You have to at least configure where to find the JS file to be used whenever a document
uses this extension, also in `conf.py`:
``` python
nostalgistjs_script_url = "https://unpkg.com/nostalgist"
```
In this case, we are using UNPKG as a CDN. You can always download a release of NostalgisJS and place it
in your `_static` folder, loading it like so:
``` python
nostalgistjs_script_url = "/_static/nostalgist.js"
```
If the extension was successfully installed, you can include an emulator in a document, using the following directive:
For reStructuredText:
:::{nostalgistjs}
:rom_url: "30yearsofnintendont.bin"
:core_id: genesis_plus_gx
:::
For Myst: (used throughout this document)
```{nostalgistjs}
:rom_url: "30yearsofnintendont.bin"
:core_id: genesis_plus_gx
```
This will embed an emulator that loads the given ROM with the respective emulation core.
If `rom_url` is not an URL, and instead, just a plain filename, NostalgistJS will try to load the ROM from [retrobrews](https://retrobrews.github.io/), as of the latest version. This uses the file extesnsion in an attempt to determine the target system automatically. The core is not important in this case.
Please consult the [launch(...) API](https://nostalgist.js.org/apis/launch/) of NostalgistJS to understand these arguments, and the available cores. As for the core to use, as a general rule:
| System | Core |
|------------|------|
| Mega Drive | genesis_plus_gx |
| NES | fceumm |
| SNES | snes9x |
| GB, GBC, GBA | mgba |
```{warning}
Some configuration options allow a document's author to inject arbitrary JavaScript into the page.
This plugin is not appropriate for environments where this may be a security issue.
``````
## Advanced Usage
It is possible to change most parameters of NostalgistJS using the directive.
Inside the directive, if there is any content, there must be a JSON object that can configure the
emulator in various ways. Most notably, the `'nostalgist_options'` is an object that
can be used to add options to be passed to the [launch(...) API](https://nostalgist.js.org/apis/launch/) of
NostalgistJS.
Here is an example of advanced usage.
This injects preamble JS code to setup input device types and mappings, specific to the ROM being used.
It can get a bit ugly, though:
```{nostalgistjs}
:rom_url: "https://example.site/rom.bin"
:core_id: genesis_plus_gx
{
"nostalgist_options": {
"retroarchConfig": {
"video_smooth": true,
"input_auto_mouse_grab": true
}
},
"before_launch_preamble": "let efs = nostalgist.getEmscriptenFS(); efs.mkdirTree('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX'); efs.writeFile('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX/rom.rmp', 'input_libretro_device_p1 = \"1\"\\ninput_libretro_device_p2 = \"2\"');"
}
```
## Directive options
### `nostalgist_options`
These are the options passed straight to NostalgistJS for configuring the emulator.
Consult the [NostalgistJS documentation](https://nostalgist.js.org/apis/launch/) for more info.
The options `rom` and `core` are filled in from the directive's `rom_url` and `core_id` parameters, and don't need to be specified again.
Also, `respondToGlobalEvents` is set to false by default, but this can be overriden.
Note that there's no need to specify the `element` option, this is handled automatically by the plugin.
Doing so will break the UI controls.
### `omit_attribution`
A boolean. If set to true, this will hide the credits that are rendered at the bottom. Defaults to false.
### `extra_nostalgist_options`
A string. This will be output directly in the JavaScript source, inside an object literal. The resulting
object is merged into the options object used for launching NostalgistJS.
This can be used to add options that cannot be expressed in JSON, such as callback functions.
Defaults to an empty string.
### Custom code injection
#### `before_launch_preamble`
A piece of JS code to be executed before the emulator starts, and before any UI setup code runs.
#### `before_launch_epilogue`
A piece of JS code to be executed before the emulator starts, but after all UI setup code runs.
#### `on_launch_preamble`
A piece of JS code to be executed after the emulator starts, but before any UI setup code runs.
#### `on_launch_epilogue`
A piece of JS code to be executed after the emulator starts, and after all UI setup code runs.
## Troubleshooting
In case the ROM doesn't load, it may be related to CORS configuration issues.
Please refer to the browser's "Developer Tools" console and network tabs for clues of
what may be happening.
## License
This project is licensed under the GPLv3 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-nostalgistjs",
"maintainer": "Lucas Pires Camargo",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "documentation, sphinx, extension, nostalgistjs, emulation, games",
"author": "Lucas Pires Camargo",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6b/46/d9e08d0ae6c43b6c7821d1f8355bdf364e3f3b3c570b1fc310a7d5db65cd/sphinx_nostalgistjs-1.0.2.tar.gz",
"platform": null,
"description": "# sphinx-nostalgistjs\n\nSphinx extension for embedding RetroArch in HTML documents, using [NostalgistJS](https://nostalgist.js.org/).\nStyling and layout depend on Bootstrap v5, not included.\n\nThis package is released on [pypi](https://pypi.org/project/sphinx-nostalgistjs/).\n\n<!--ENGBR_SECTION\n## Demo\n\nClick to start. Use the Z key to jump, and the Enter key to start.\nThis is emulating \"flappybird.nes\" on the \"FCEUmm\" core in RetroArch.\n\n```{nostalgistjs}\n :rom_url: \"flappybird.nes\"\n :core_id: fceumm\n {\n \"omit_attribution\": true\n }\n```\nENGBR_SECTION-->\n\n\n\n## Basic Usage\n\nAdd this extension to your Sphinx `conf.py`, like so:\n\n``` python\nextensions = [\n \"sphinx_nostalgistjs\",\n \u22ef\n]\n```\n\nYou have to at least configure where to find the JS file to be used whenever a document\nuses this extension, also in `conf.py`:\n\n``` python\nnostalgistjs_script_url = \"https://unpkg.com/nostalgist\"\n```\n\nIn this case, we are using UNPKG as a CDN. You can always download a release of NostalgisJS and place it\nin your `_static` folder, loading it like so:\n\n``` python\nnostalgistjs_script_url = \"/_static/nostalgist.js\"\n```\n\nIf the extension was successfully installed, you can include an emulator in a document, using the following directive:\n\n For reStructuredText:\n :::{nostalgistjs}\n :rom_url: \"30yearsofnintendont.bin\"\n :core_id: genesis_plus_gx\n ::: \n \n For Myst: (used throughout this document)\n ```{nostalgistjs}\n :rom_url: \"30yearsofnintendont.bin\"\n :core_id: genesis_plus_gx\n ```\n\nThis will embed an emulator that loads the given ROM with the respective emulation core.\nIf `rom_url` is not an URL, and instead, just a plain filename, NostalgistJS will try to load the ROM from [retrobrews](https://retrobrews.github.io/), as of the latest version. This uses the file extesnsion in an attempt to determine the target system automatically. The core is not important in this case.\n\nPlease consult the [launch(...) API](https://nostalgist.js.org/apis/launch/) of NostalgistJS to understand these arguments, and the available cores. As for the core to use, as a general rule:\n\n| System | Core |\n|------------|------|\n| Mega Drive | genesis_plus_gx |\n| NES | fceumm |\n| SNES | snes9x |\n| GB, GBC, GBA | mgba |\n\n\n```{warning}\nSome configuration options allow a document's author to inject arbitrary JavaScript into the page.\nThis plugin is not appropriate for environments where this may be a security issue.\n``````\n\n## Advanced Usage\n\nIt is possible to change most parameters of NostalgistJS using the directive.\n\nInside the directive, if there is any content, there must be a JSON object that can configure the\nemulator in various ways. Most notably, the `'nostalgist_options'` is an object that\ncan be used to add options to be passed to the [launch(...) API](https://nostalgist.js.org/apis/launch/) of\nNostalgistJS.\n\nHere is an example of advanced usage.\nThis injects preamble JS code to setup input device types and mappings, specific to the ROM being used.\nIt can get a bit ugly, though:\n\n ```{nostalgistjs}\n :rom_url: \"https://example.site/rom.bin\"\n :core_id: genesis_plus_gx\n {\n \"nostalgist_options\": {\n \"retroarchConfig\": {\n \"video_smooth\": true,\n \"input_auto_mouse_grab\": true\n }\n },\n \"before_launch_preamble\": \"let efs = nostalgist.getEmscriptenFS(); efs.mkdirTree('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX'); efs.writeFile('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX/rom.rmp', 'input_libretro_device_p1 = \\\"1\\\"\\\\ninput_libretro_device_p2 = \\\"2\\\"');\"\n }\n ```\n\n## Directive options\n\n### `nostalgist_options`\n\nThese are the options passed straight to NostalgistJS for configuring the emulator. \nConsult the [NostalgistJS documentation](https://nostalgist.js.org/apis/launch/) for more info. \n\nThe options `rom` and `core` are filled in from the directive's `rom_url` and `core_id` parameters, and don't need to be specified again. \nAlso, `respondToGlobalEvents` is set to false by default, but this can be overriden.\n\nNote that there's no need to specify the `element` option, this is handled automatically by the plugin.\nDoing so will break the UI controls.\n\n### `omit_attribution`\n\nA boolean. If set to true, this will hide the credits that are rendered at the bottom. Defaults to false.\n\n### `extra_nostalgist_options`\n\nA string. This will be output directly in the JavaScript source, inside an object literal. The resulting \nobject is merged into the options object used for launching NostalgistJS.\n\nThis can be used to add options that cannot be expressed in JSON, such as callback functions. \nDefaults to an empty string.\n\n### Custom code injection\n\n#### `before_launch_preamble`\n\nA piece of JS code to be executed before the emulator starts, and before any UI setup code runs.\n\n#### `before_launch_epilogue`\n\nA piece of JS code to be executed before the emulator starts, but after all UI setup code runs.\n\n#### `on_launch_preamble`\n\nA piece of JS code to be executed after the emulator starts, but before any UI setup code runs.\n\n#### `on_launch_epilogue`\n\nA piece of JS code to be executed after the emulator starts, and after all UI setup code runs.\n\n## Troubleshooting\n\nIn case the ROM doesn't load, it may be related to CORS configuration issues.\nPlease refer to the browser's \"Developer Tools\" console and network tabs for clues of\nwhat may be happening.\n\n## License\n\nThis project is licensed under the GPLv3 license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Sphinx extension for embeding Isso comments in documents",
"version": "1.0.2",
"project_urls": {
"homepage": "https://camargo.eng.br/projects/sphinx-nostalgistjs/README.html",
"repository": "https://github.com/lucaspcamargo/sphinx-nostalgistjs",
"tracker": "https://github.com/lucaspcamargo/sphinx-nostalgistjs/issues"
},
"split_keywords": [
"documentation",
" sphinx",
" extension",
" nostalgistjs",
" emulation",
" games"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48f2a47dbe4b45b6b87d7c0f3b3af7e9331c8243ce6e3fc1fb8f27c55ace4e56",
"md5": "a4489e886a0c7db7bf67cd7051db0863",
"sha256": "61a294e288f8e42996fd7865636e0801633360c010f777f6cd1e5cefbde63e65"
},
"downloads": -1,
"filename": "sphinx_nostalgistjs-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4489e886a0c7db7bf67cd7051db0863",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19682,
"upload_time": "2024-04-19T21:38:04",
"upload_time_iso_8601": "2024-04-19T21:38:04.949480Z",
"url": "https://files.pythonhosted.org/packages/48/f2/a47dbe4b45b6b87d7c0f3b3af7e9331c8243ce6e3fc1fb8f27c55ace4e56/sphinx_nostalgistjs-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b46d9e08d0ae6c43b6c7821d1f8355bdf364e3f3b3c570b1fc310a7d5db65cd",
"md5": "5c0c9a3d812c387a10146b983c96a7e9",
"sha256": "b1599aee9374d6f382d5c5e33c82629c0290dc41f4df54f828c78acc284c3eff"
},
"downloads": -1,
"filename": "sphinx_nostalgistjs-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5c0c9a3d812c387a10146b983c96a7e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23077,
"upload_time": "2024-04-19T21:38:06",
"upload_time_iso_8601": "2024-04-19T21:38:06.796673Z",
"url": "https://files.pythonhosted.org/packages/6b/46/d9e08d0ae6c43b6c7821d1f8355bdf364e3f3b3c570b1fc310a7d5db65cd/sphinx_nostalgistjs-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 21:38:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucaspcamargo",
"github_project": "sphinx-nostalgistjs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-nostalgistjs"
}
JSON
