| Name | sphinx-iframes JSON |
| Version |
1.0.6
JSON |
| download |
| home_page | None |
| Summary | A custom Sphinx extension to easily embed iframes in a Sphinx book |
| upload_time | 2025-07-18 08:52:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 TeachBooks
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. |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sphinx extension: Iframes
## Introduction
This extension provides an interface to include iframes with relative ease, but does try to provide manners to interact with the various options. This rests purely by setting default CSS values, that the user can overwrite if preferred for individual iframes, but also globally. In general, each `iframe` is embedded within a `div` element, which eases sizing.
> [!NOTE]
> Using CSS is complicated and error prone, so always check and never expect that you get what you want.
## What does it do?
This extension provides several Sphinx directives:
- `iframe`
- `h5p`
- `video`
- `iframe-figure`
that can be used to quickly insert an iframe with standard sizing and styling.
## Installation
To use this extenstion, follow these steps:
**Step 1: Install the Package**
Install the module `sphinx-iframes` package using `pip`:
```
pip install sphinx-iframes
```
**Step 2: Add to `requirements.txt`**
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
```
sphinx-iframes
```
**Step 3: Enable in `_config.yml`**
In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
```
sphinx:
extra_extensions:
.
.
.
- sphinx_iframes
.
.
.
```
## Configuration
The extension provides several configuration values, which can be added to `_config.yml`:
```yaml
sphinx:
config:
-
-
-
iframe_blend: true # default value
iframe_saturation: 1.5 # default value
iframe_h5p_autoresize: true # default value
iframe_background: "#ffffff" # default value
iframe_width: calc(100% - 2.8rem) # default value
iframe_aspectratio: auto 2 / 1 # default value
-
-
-
```
- `iframe_blend`: `true` (_default_) or `false`:
- if `true` all iframes are standard blended with the background and in dark-mode also inverted.
- if `false` all non-blended iframes will have background a colored background and no inversion for dark-mode is applied.
- there's no need to set the blend or no-blend for individual iframes if it's set in the `_config.yml`, unless you want to deviate from the setting set there.
- `iframe_saturation`: `1.5` (_default_) or **float**:
- Blended iframes are inverted in darkmode using the CSS filter `invert(1) hue-rotate(180deg) saturation(iframe_saturation)`.
- `iframe_h5p_autoresize`: `true` (_default_) or `false`:
- if `true` all h5p iframes are automagically resized to fit the element in which the iframe is loaded.
- if `false` no h5p iframes are automagically resized to fit the element in which the iframe is loaded.
- `iframe_background`: `"#ffffff"` (_default_) or **CSS string**:
- sets the standard background color of non-blended iframes.
- Any CSS string defining colors can be used, see [<color> CSS data type](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
- Surround with `" "` for hex strings.
- Only visible if the content of the iframes has a transparant background.
- `iframe_width`: `calc(100% - 2.8rem)` (_default_) or **CSS string**:
- sets the standard width of the iframe within the parent element;
- Any CSS string defining a width can be used, see [width CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/width).
- `iframe_aspectratio`: `auto 2 / 1` (_default_) or **CSS string**:
- sets the standard aspect ration of the iframe within the parent element;
- Any CSS string defining an aspect ratio can be used, see [aspect-ratio CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio).
## Provided code
### Directives
The following new directives are provided:
````md
```{iframe} <link_to_webpage_to_embed>
```
````
````md
```{h5p} <link_to_h5p_webpage_to_embed>
```
````
````md
```{video} <link_to_video_to_embed>
```
````
In case of a YouTube-link, it is inverted to an embed link if the normal web URL is provided. H5p links are converted too if provided without `/embed`.
````md
```{iframe-figure} <link_to_webpage_to_embed>
:name: some:label
The caption for the iframe.
```
````
Note that you don't need the full embed code of an iframe. Only the source url should be used.
All of these have the following options:
- `:class:`
- If further CSS styling is needed, then use this option to append a CSS class name to the rendered iframe.
- We recommend to only use the classes `blend` and `no-blend`, see [](sec:iframes:examples).
- `:width:`
- Sets the width of the iframe. Use CSS compatible strings.
- `:height:`
- Sets the width of the iframe. Use CSS compatible strings.
- `:aspectratio:`
- Sets the width of the iframe. Use CSS compatible strings.
- `:styleframe:`
- Sets the style of the iframe. Use CSS compatible strings. Surround with " ".
- `:stylediv:`
- Sets the style of the surrounding div. Use CSS compatible strings. Surround with " ".
The directive `iframe-figure` also inherits all options from the `figure` directive from Sphinx.
(sec:iframes:examples)=
## Examples and details
To see examples of usage visit [this page in the TeachBooks manual](https://teachbooks.io/manual/external/sphinx-iframes/README.html).
## Contribute
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/sphinx-iframes). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/sphinx-iframes).
The `README.md` of the branch `Manual` is also part of the [TeachBooks manual](https://teachbooks.io/manual/intro.html) as a submodule.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-iframes",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Dennis den Ouden-van der Horst <d.denouden-vanderhorst@tudelft.nl>",
"download_url": "https://files.pythonhosted.org/packages/e3/fe/8408fd975f34f4a144a8ec8aaa5468021623542cb720739c87d152fdbf23/sphinx_iframes-1.0.6.tar.gz",
"platform": null,
"description": "# Sphinx extension: Iframes\n\n## Introduction\n\nThis extension provides an interface to include iframes with relative ease, but does try to provide manners to interact with the various options. This rests purely by setting default CSS values, that the user can overwrite if preferred for individual iframes, but also globally. In general, each `iframe` is embedded within a `div` element, which eases sizing.\n\n> [!NOTE]\n> Using CSS is complicated and error prone, so always check and never expect that you get what you want.\n\n## What does it do?\n\nThis extension provides several Sphinx directives:\n\n- `iframe`\n- `h5p`\n- `video`\n- `iframe-figure`\n\n that can be used to quickly insert an iframe with standard sizing and styling.\n\n## Installation\nTo use this extenstion, follow these steps:\n\n**Step 1: Install the Package**\n\nInstall the module `sphinx-iframes` package using `pip`:\n```\npip install sphinx-iframes\n```\n \n**Step 2: Add to `requirements.txt`**\n\nMake sure that the package is included in your project's `requirements.txt` to track the dependency:\n```\nsphinx-iframes\n```\n\n**Step 3: Enable in `_config.yml`**\n\nIn your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):\n```\nsphinx: \n extra_extensions:\n .\n .\n .\n - sphinx_iframes\n .\n .\n .\n```\n\n## Configuration\n\nThe extension provides several configuration values, which can be added to `_config.yml`:\n\n```yaml\nsphinx: \n config:\n -\n -\n -\n iframe_blend: true # default value\n iframe_saturation: 1.5 # default value\n iframe_h5p_autoresize: true # default value\n iframe_background: \"#ffffff\" # default value\n iframe_width: calc(100% - 2.8rem) # default value\n iframe_aspectratio: auto 2 / 1 # default value\n -\n -\n -\n```\n\n- `iframe_blend`: `true` (_default_) or `false`:\n - if `true` all iframes are standard blended with the background and in dark-mode also inverted.\n - if `false` all non-blended iframes will have background a colored background and no inversion for dark-mode is applied.\n - there's no need to set the blend or no-blend for individual iframes if it's set in the `_config.yml`, unless you want to deviate from the setting set there.\n- `iframe_saturation`: `1.5` (_default_) or **float**:\n - Blended iframes are inverted in darkmode using the CSS filter `invert(1) hue-rotate(180deg) saturation(iframe_saturation)`.\n- `iframe_h5p_autoresize`: `true` (_default_) or `false`:\n - if `true` all h5p iframes are automagically resized to fit the element in which the iframe is loaded.\n - if `false` no h5p iframes are automagically resized to fit the element in which the iframe is loaded.\n- `iframe_background`: `\"#ffffff\"` (_default_) or **CSS string**:\n - sets the standard background color of non-blended iframes.\n - Any CSS string defining colors can be used, see [<color> CSS data type](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).\n - Surround with `\" \"` for hex strings.\n - Only visible if the content of the iframes has a transparant background. \n- `iframe_width`: `calc(100% - 2.8rem)` (_default_) or **CSS string**:\n - sets the standard width of the iframe within the parent element;\n - Any CSS string defining a width can be used, see [width CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/width).\n- `iframe_aspectratio`: `auto 2 / 1` (_default_) or **CSS string**:\n - sets the standard aspect ration of the iframe within the parent element;\n - Any CSS string defining an aspect ratio can be used, see [aspect-ratio CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio).\n\n## Provided code\n\n### Directives\n\nThe following new directives are provided:\n\n````md\n```{iframe} <link_to_webpage_to_embed>\n```\n````\n\n````md\n```{h5p} <link_to_h5p_webpage_to_embed>\n```\n````\n\n````md\n```{video} <link_to_video_to_embed>\n```\n````\n\nIn case of a YouTube-link, it is inverted to an embed link if the normal web URL is provided. H5p links are converted too if provided without `/embed`.\n\n````md\n```{iframe-figure} <link_to_webpage_to_embed>\n:name: some:label\n\nThe caption for the iframe.\n```\n````\n\nNote that you don't need the full embed code of an iframe. Only the source url should be used.\n\nAll of these have the following options:\n\n- `:class:`\n - If further CSS styling is needed, then use this option to append a CSS class name to the rendered iframe.\n - We recommend to only use the classes `blend` and `no-blend`, see [](sec:iframes:examples).\n- `:width:`\n - Sets the width of the iframe. Use CSS compatible strings.\n- `:height:`\n - Sets the width of the iframe. Use CSS compatible strings.\n- `:aspectratio:`\n - Sets the width of the iframe. Use CSS compatible strings.\n- `:styleframe:`\n - Sets the style of the iframe. Use CSS compatible strings. Surround with \" \".\n- `:stylediv:`\n - Sets the style of the surrounding div. Use CSS compatible strings. Surround with \" \".\n\nThe directive `iframe-figure` also inherits all options from the `figure` directive from Sphinx.\n\n(sec:iframes:examples)=\n## Examples and details\n\nTo see examples of usage visit [this page in the TeachBooks manual](https://teachbooks.io/manual/external/sphinx-iframes/README.html).\n\n## Contribute\n\nThis tool's repository is stored on [GitHub](https://github.com/TeachBooks/sphinx-iframes). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/sphinx-iframes).\n\nThe `README.md` of the branch `Manual` is also part of the [TeachBooks manual](https://teachbooks.io/manual/intro.html) as a submodule.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 TeachBooks\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A custom Sphinx extension to easily embed iframes in a Sphinx book",
"version": "1.0.6",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0665832db313b11b5cf25343e75ba146c735051d1c446a635cd280720a977b28",
"md5": "1431f8471f73ba62c7dd086670587ffe",
"sha256": "e7541ff3a632bfaa03ad97fb0c9194a9647063726ddd334f911e169166979d7b"
},
"downloads": -1,
"filename": "sphinx_iframes-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1431f8471f73ba62c7dd086670587ffe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9004,
"upload_time": "2025-07-18T08:52:50",
"upload_time_iso_8601": "2025-07-18T08:52:50.282206Z",
"url": "https://files.pythonhosted.org/packages/06/65/832db313b11b5cf25343e75ba146c735051d1c446a635cd280720a977b28/sphinx_iframes-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e3fe8408fd975f34f4a144a8ec8aaa5468021623542cb720739c87d152fdbf23",
"md5": "fd280eb75d3baeaba46aa00d38009671",
"sha256": "2212ff00ff2bc4be01d2b72982c5e81337a3ef0de4b70de32a7f634c097b7a21"
},
"downloads": -1,
"filename": "sphinx_iframes-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "fd280eb75d3baeaba46aa00d38009671",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11962,
"upload_time": "2025-07-18T08:52:51",
"upload_time_iso_8601": "2025-07-18T08:52:51.744296Z",
"url": "https://files.pythonhosted.org/packages/e3/fe/8408fd975f34f4a144a8ec8aaa5468021623542cb720739c87d152fdbf23/sphinx_iframes-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 08:52:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sphinx-iframes"
}
