| Name | sphinx-inline-svg JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension to make svg images inline |
| upload_time | 2024-10-15 15:27:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
extension
inline
sphinx
svg
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-inline-svg
[≫日本語版](https://github.com/satamame/sphinx-inline-svg/blob/main/README_ja.md)
## Overview
Sphinx extension to make SVG images inline.
It helps to make text in SVG into hyperlink.
If the builder is not `html`, it has no effect.
## Installation
### pip
```
pip install sphinx-inline-svg
```
### rye
```
rye add --dev sphinx-inline-svg
```
## Usage
### conf.py
Add it to `extensions`.
```python
# conf.py
extensions = [
'sphinx_inline_svg',
]
```
### Add CSS class
Add CSS class to SVG image to be inlined.
```
.. image:: img/chart.drawio.svg
:class: inline-svg
```
As for MyST, enable `attrs_inline` in conf.py.
```python
# conf.py
myst_enable_extensions = [
"attrs_inline",
]
```
```markdown
{.inline-svg}
```
Define `inline-svg` class in CSS if actual style is needed.
```css
/* _static/css/custom.css */
/* example */
.inline-svg {
max-width: 100%;
height: auto;
}
```
And add it in conf.py as follows.
```python
# conf.py
def setup(app):
app.add_css_file('css/custom.css')
```
> [!NOTE]
> Even if you don't define actual style, giving the class will inline SVGs.
## Hyperlink
To make text in SVG a hyperlink, for example, edit it as follows in [draw.io](https://app.diagrams.net).
### Link notation
Link destination that is generated after build depends on Link notation.
|Notation|Generated destination|Example|Destination for example|
|-|-|-|-|
|Starts with "/".|Path from project root.|/index.rst|Top page.|
|Starts with "#".|Defined cross-reference target.|#target-1|Position defined as "#target-1" in the project.|
|Starts with "http://" and so on.|As is.|https:​//google​.com|The site on the Internet.|
|Other than above.|Relative path from the page.|detail.rst|detail.html file in the same directory.|
> [!NOTE]
> As for the last notation, generated destination is relative from the page where SVG is extracted to, not from the SVG itself.
## Configuration
The following settings can be configured in conf.py. If you do not write the configuration itself, the default value is applied.
```python
# conf.py
inline_svg_classes = ['inline-svg', 'selectable-svg']
```
|Name|Type|Description|Default value|
|-|-|-|-|
|inline_svg_classes|`list[str]`|List of class names. SVG image with any of these will be inlined.|`['inline-svg']`|
|inline_svg_del_attrs|`list[str]`|List of attribute names to be deleted from svg element when extracted.|`['content']`|
|inline_svg_resolve_xref|`bool`|Whether to convert destination as described in the above "Link notation" section.|`True`|
> [!NOTE]
> The svg element in SVG file saved by draw.io has "content" attribute, but this is data for editing by the draw.io app, so it is not necessary for the svg element to be inlined.
## Known problems
It has been reported that inlining SVG images saved by [Draw.io Integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension of VSCode with sphinx-inline-svg results in garbled characters. 😥
In addition, hyperlinks in SVG images saved by Draw.io Integration may not become clickable. In such cases, inlining with sphinx-inline-svg does not make them clickable. 😥
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-inline-svg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "extension, inline, sphinx, svg",
"author": null,
"author_email": "satamame <satamame@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/96/de/0d4f7596bb958c67fa9b4c4982239e28f81cc97724fe5ed4fb39905ecfe0/sphinx_inline_svg-0.1.2.tar.gz",
"platform": null,
"description": "# sphinx-inline-svg\n\n[\u226b\u65e5\u672c\u8a9e\u7248](https://github.com/satamame/sphinx-inline-svg/blob/main/README_ja.md)\n\n## Overview\n\nSphinx extension to make SVG images inline. \nIt helps to make text in SVG into hyperlink. \nIf the builder is not `html`, it has no effect.\n\n## Installation\n\n### pip\n\n```\npip install sphinx-inline-svg\n```\n\n### rye\n\n```\nrye add --dev sphinx-inline-svg\n```\n\n## Usage\n\n### conf.py\n\nAdd it to `extensions`.\n\n```python\n# conf.py\n\nextensions = [\n 'sphinx_inline_svg',\n]\n```\n\n### Add CSS class\n\nAdd CSS class to SVG image to be inlined.\n\n```\n.. image:: img/chart.drawio.svg\n :class: inline-svg\n```\n\nAs for MyST, enable `attrs_inline` in conf.py.\n\n```python\n# conf.py\n\nmyst_enable_extensions = [\n \"attrs_inline\",\n]\n```\n\n```markdown\n{.inline-svg}\n```\n\nDefine `inline-svg` class in CSS if actual style is needed.\n\n```css\n/* _static/css/custom.css */\n\n/* example */\n.inline-svg {\n max-width: 100%;\n height: auto;\n}\n```\n\nAnd add it in conf.py as follows.\n\n```python\n# conf.py\n\ndef setup(app):\n app.add_css_file('css/custom.css')\n```\n\n> [!NOTE]\n> Even if you don't define actual style, giving the class will inline SVGs.\n\n## Hyperlink\n\nTo make text in SVG a hyperlink, for example, edit it as follows in [draw.io](https://app.diagrams.net).\n\n\n\n\n\n### Link notation\n\nLink destination that is generated after build depends on Link notation.\n\n|Notation|Generated destination|Example|Destination for example|\n|-|-|-|-|\n|Starts with \"/\".|Path from project root.|/index.rst|Top page.|\n|Starts with \"#\".|Defined cross-reference target.|#target-1|Position defined as \"#target-1\" in the project.|\n|Starts with \"http://\" and so on.|As is.|https:​//google​.com|The site on the Internet.|\n|Other than above.|Relative path from the page.|detail.rst|detail.html file in the same directory.|\n\n> [!NOTE]\n> As for the last notation, generated destination is relative from the page where SVG is extracted to, not from the SVG itself.\n\n## Configuration\n\nThe following settings can be configured in conf.py. If you do not write the configuration itself, the default value is applied.\n\n```python\n# conf.py\n\ninline_svg_classes = ['inline-svg', 'selectable-svg']\n```\n\n|Name|Type|Description|Default value|\n|-|-|-|-|\n|inline_svg_classes|`list[str]`|List of class names. SVG image with any of these will be inlined.|`['inline-svg']`|\n|inline_svg_del_attrs|`list[str]`|List of attribute names to be deleted from svg element when extracted.|`['content']`|\n|inline_svg_resolve_xref|`bool`|Whether to convert destination as described in the above \"Link notation\" section.|`True`|\n\n> [!NOTE]\n> The svg element in SVG file saved by draw.io has \"content\" attribute, but this is data for editing by the draw.io app, so it is not necessary for the svg element to be inlined.\n\n## Known problems\n\nIt has been reported that inlining SVG images saved by [Draw.io Integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension of VSCode with sphinx-inline-svg results in garbled characters. \ud83d\ude25\n\nIn addition, hyperlinks in SVG images saved by Draw.io Integration may not become clickable. In such cases, inlining with sphinx-inline-svg does not make them clickable. \ud83d\ude25\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx extension to make svg images inline",
"version": "0.1.2",
"project_urls": {
"Changelog": "https://github.com/satamame/sphinx-inline-svg/releases",
"Homepage": "https://github.com/satamame/sphinx-inline-svg",
"Issues": "https://github.com/satamame/sphinx-inline-svg/issues",
"Repository": "https://github.com/satamame/sphinx-inline-svg.git"
},
"split_keywords": [
"extension",
" inline",
" sphinx",
" svg"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32aacc44aa9e633e04cea2fb2359ff8faff821b1d58f87f53e7783164d730d9f",
"md5": "990cb623464facdd333b69e5cc25fd3b",
"sha256": "12672d534b9d5788b8725ee000efaf7b93f130cb0228a5d4e4393ffb38315239"
},
"downloads": -1,
"filename": "sphinx_inline_svg-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "990cb623464facdd333b69e5cc25fd3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6176,
"upload_time": "2024-10-15T15:27:54",
"upload_time_iso_8601": "2024-10-15T15:27:54.501312Z",
"url": "https://files.pythonhosted.org/packages/32/aa/cc44aa9e633e04cea2fb2359ff8faff821b1d58f87f53e7783164d730d9f/sphinx_inline_svg-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96de0d4f7596bb958c67fa9b4c4982239e28f81cc97724fe5ed4fb39905ecfe0",
"md5": "1c5c992b8a30d60a41d5e8c985cd70f3",
"sha256": "138d2d8fc1ab963b7a3a35547f321254fd6355d3f24748148fc31d5658d10294"
},
"downloads": -1,
"filename": "sphinx_inline_svg-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1c5c992b8a30d60a41d5e8c985cd70f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 76379,
"upload_time": "2024-10-15T15:27:55",
"upload_time_iso_8601": "2024-10-15T15:27:55.852006Z",
"url": "https://files.pythonhosted.org/packages/96/de/0d4f7596bb958c67fa9b4c4982239e28f81cc97724fe5ed4fb39905ecfe0/sphinx_inline_svg-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 15:27:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "satamame",
"github_project": "sphinx-inline-svg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "sphinx-inline-svg"
}
