# sphinxcontrib-drawio
Sphinx Extension adding the `drawio-image` and `drawio-figure` directives.
These are equivalent to the standard `image` and `figure` directives, but
accept the path to a `.drawio` file and additional options to control
exporting of the diagram to a suitable image format.
**Important:** This extension does not work on readthedocs as RTD does not allow
packages (e.g. drawio) to be installed. If you only require diagrams in a single
format, you can consider using editable SVGs or PNGs, accessible through
draw.io's File > Export menu.
The drawio-desktop package does not run without an x-server (e.g. when in a CI
environment), see [this issue](https://github.com/jgraph/drawio-desktop/issues/146).
The workaround is to install `xvfb` and set the `drawio_headless` configuration
option to `auto`.
If any other of the `draw.io` CLI tool's options are wanted, please file an
issue.
## Installation
1. `python3 -m pip install sphinxcontrib-drawio`
2. In your sphinx config, add:
```python
extensions = [
"sphinxcontrib.drawio"
]
```
3. Add the draw.io binary to `$PATH`. See [Options: Binary Path](#binary-path)
for more details and alternative solutions.
4. If running headless, install Xvfb, e.g. via `$ sudo apt install xvfb`.
## Options
These values are placed in the `conf.py` of your sphinx project.
### Binary Path
- *Formal Name*: `drawio_binary_path`
- *Default Value*: `None`
This allows for a specific override for the binary location. By default, this
chooses the `drawio` (or `draw.io.exe`) binary accessible in `$PATH`. However,
if this file does not exist, it picks the platform-appropriate path:
- Windows: `C:\Program Files\draw.io\draw.io.exe`
- Linux: `/opt/drawio/drawio` or `/opt/draw.io/drawio` (older versions)
- MacOS: `/Applications/draw.io.app/Contents/MacOS/draw.io`.
### Headless Mode
- *Formal Name*: `drawio_headless`
- *Default Value*: `"auto"`
- *Possible Values*: `True`, `False`, or `"auto"`
This config option controls the behaviour of running the Xvfb server. It is
necessary because `draw.io` will not work without an X-server, see
[this issue](https://github.com/jgraph/drawio-desktop/issues/146).
The `auto` mode will detect whether the program is running in a headless
environment through the `$DISPLAY` environment variable, and act as if it were
set to `True`. If not running on Linux, or the `$DISPLAY` environment variable
contains some value (i.e. running in an X-server on a developer's machine), it
will act as it it were set to `False`.
Setting the value to `True` will start a virtual X framebuffer through the
`Xvfb` command before running any `draw.io` commands, and stop it afterwards.
Setting the value to `False` will run the `draw.io` binary as normal.
### Default Output Format
- *Formal Name*: `drawio_builder_export_format`
- *Default Value*: `{}`
This config option controls the default export file format for each Sphinx
builder. It accepts a dictionary mapping builder names to image formats. The
builder name should match the name of a [Sphinx builder](https://www.sphinx-doc.org/en/master/usage/builders/index.html)
(e.g., `"html"`, `"latex"`). Accepted values for the export format are `"png"`,
`"jpg"`, `"svg"` and `"pdf"`. If no format is set for a given builder, its
preferred image format is used, that is, the first format listed in a builder's
_supported_image_types_ that draw.io is capable of exporting to (eg. SVG for
HTML, PDF for LaTeX).
### Default Export Scale
- *Formal Name*: `drawio_default_export_scale`
- *Default Value*: `100`
- *Possible Values*: any positive integer
This config option sets the default export scale for all diagrams. This scales
the size of the diagram. So if you take a diagram that by default would output
a image with a resolution of 50x50 pixels and a scale of 200, you will obtain an
image with a resolution that is approximately 100x100 pixels. By default draw.io
*usually* outputs relatively low resolution images, so this setting can be used
to remedy that.
This setting will get automatically overridden if the `scale` is set for a
individual diagram in the directive. If either `export-width` or `export-height`
are set for an image, this option will have no effect on the generated image.
### Default Transparency
- *Formal Name*: `drawio_default_transparency`
- *Default Value*: `False`
- *Possible Values*: `True` or `False`
This changes the background transparency for diagrams exported in *png* format.
This will be overridden if the transparency is set for a individual diagram in
the directive. If the output format isn't *png*, it will not affect the image
exported.
### Disable Verbose Electron
- *Formal Name*: `drawio_disable_verbose_electron`
- *Default Value*: `False`
- *Possible Values*: `True` or `False`
Electron's verbose logging is turned on by default to help troubleshoot certain
errors produced by the drawio app, but can be disabled if it causes a logging
conflict. This option only affects the output when the drawio app errors. See the
[Electron docs](https://www.electronjs.org/docs/latest/api/command-line-switches#--enable-loggingfile)
for more info.
### Disable Shared Memory Usage
- *Formal Name*: `drawio_disable_dev_shm_usage`
- *Default Value*: `False`
- *Possible Values*: `True` or `False`
By default, Docker runs a container with a `/dev/shm` shared memory space of 64MB.
This is typically too small for Chrome (Electron) and will cause Chrome to throw
an error. Launching the browser with the `--disable-dev-shm-usage` flag will write
shared memory files into `/tmp` instead of `/dev/shm`.
### Disable GPU
- *Formal Name*: `drawio_disable_gpu`
- *Default Value*: `False`
- *Possible Values*: `True` or `False`
By default, Chrome (Electron) uses GPU processes which can cause errors when
running in environments that are not set up for it. This option disables those
GPU processes and uses the CPU instead.
### No Sandbox
- *Formal Name*: `drawio_no_sandbox`
- *Default Value*: `False`
- *Possible Values*: `True` or `False`
This option may be needed to work in a docker container. You should probably
only enable it if you are experiencing issues. See https://github.com/jgraph/drawio-desktop/issues/144
for more info.
## Usage
The extension can be used through the `drawio-image` directive. For example:
```
.. drawio-image:: example.drawio
:export-scale: 150
```
There's also a `drawio-figure` directive that mimics the `figure` directive:
```
.. drawio-figure:: example.drawio
:format: png
An example diagram
```
The directives can be configured with options to control the export of the
draw.io diagram to a bitmap or vector image. These options are documented below.
Additionally, `drawio-image` accepts all of the options supported by the
[image directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image).
These options apply to the image as exported by draw.io. Similarly,
`drawio-figure` accepts all options supported by the [figure directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure).
### Format
- *Formal Name*: `:format:`
- *Default Value*: `"png"`
- *Possible Values*: `"png"`, `"jpg"`, `"svg"` or `"pdf"`
This option controls the output file format of *this specific* directive.
### Page Index
- *Formal Name*: `:page-index:`
- *Default Value*: `0`
- *Possible Values*: any integer
This option allows you to select a particular page from a draw.io file to
export. Note that an invalid page-index will revert to one of the other valid
pages (draw.io binary functionality). `page-name` and `page-index` cannot
coexist, if you set both options, an error will be reported.
### Page Name
- *Formal Name*: `:page-name:`
- *Default Value*: value of `:page-index:`, else the first page
- *Possible Values*: any string
This option allows you to select a particular page by its name from a draw.io
file to export. `page-name` and `page-index` cannot coexist, if you set both
options, an error will be reported. If `:page-name:` is not found in the draw.io
file, an error will be reported too.
### Export Scale
- *Formal Name*: `:export-scale:`
- *Default Value*: `drawio_default_export_scale` set in conf.py
- *Possible Values*: any positive integer
This scales the size of the output image. So if you take a diagram that by
default would output a image with a resolution of 50x50 pixels and a scale of
200, you will obtain an image with a resolution that is approximately 100x100
pixels. By default draw.io *usually* outputs relatively low-resolution images,
so this setting can be used to remedy that. This overrides the
`drawio_default_export_scale` set in conf.py for this specific diagram. If
either `export-width` or `export-height` are set for a given image,
`export-scale` will have no effect on the generated image.
### Export Width
- *Formal Name*: `:export-width:`
- *Possible Values*: any positive integer
This fits the generated image into the specified width, preserving aspect ratio.
When exporting to a bitmap image, this specifies the width in pixels. For PDF,
a value of 100 corresponds to 1.00 inches.
### Export Height
- *Formal Name*: `:export-height:`
- *Possible Values*: any positive integer
This fits the generated image into the specified height, preserving aspect
ratio. When exporting to a bitmap image, this specifies the height in pixels.
For PDF, a value of 100 corresponds to 1.00 inches.
### Transparency
- *Formal Name*: `:transparency:`
- *Default Value*: `drawio_default_transparency` set in conf.py
- *Possible Values*: `"true"` or `"false"`
This changes the background transparency for diagrams exported to `png` files.
Will override `drawio_default_transparency` which was set in conf.py for this
specific diagram. If this setting is specified while the output format is not
`png` it will have no effect on the generated image
Raw data
{
"_id": null,
"home_page": "https://github.com/Modelmat/sphinxcontrib-drawio",
"name": "sphinxcontrib-drawio",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Modelmat",
"author_email": "modelmat@outlook.com.au",
"download_url": "https://files.pythonhosted.org/packages/ea/9b/45a4e9f7d5b3f3e8e3fa792f99b20d2f6d337c4b84f9e55044aecf0e60c8/sphinxcontrib-drawio-0.0.17.tar.gz",
"platform": null,
"description": "# sphinxcontrib-drawio\n\nSphinx Extension adding the `drawio-image` and `drawio-figure` directives.\nThese are equivalent to the standard `image` and `figure` directives, but\naccept the path to a `.drawio` file and additional options to control\nexporting of the diagram to a suitable image format. \n\n**Important:** This extension does not work on readthedocs as RTD does not allow\npackages (e.g. drawio) to be installed. If you only require diagrams in a single\nformat, you can consider using editable SVGs or PNGs, accessible through\ndraw.io's File > Export menu.\n\nThe drawio-desktop package does not run without an x-server (e.g. when in a CI\nenvironment), see [this issue](https://github.com/jgraph/drawio-desktop/issues/146).\nThe workaround is to install `xvfb` and set the `drawio_headless` configuration\noption to `auto`.\n\nIf any other of the `draw.io` CLI tool's options are wanted, please file an\nissue.\n\n## Installation\n\n1. `python3 -m pip install sphinxcontrib-drawio`\n2. In your sphinx config, add:\n\n ```python\n extensions = [\n \"sphinxcontrib.drawio\"\n ]\n ```\n\n3. Add the draw.io binary to `$PATH`. See [Options: Binary Path](#binary-path)\n for more details and alternative solutions.\n\n4. If running headless, install Xvfb, e.g. via `$ sudo apt install xvfb`.\n\n## Options\nThese values are placed in the `conf.py` of your sphinx project.\n\n### Binary Path\n- *Formal Name*: `drawio_binary_path`\n- *Default Value*: `None`\n\nThis allows for a specific override for the binary location. By default, this\nchooses the `drawio` (or `draw.io.exe`) binary accessible in `$PATH`. However,\nif this file does not exist, it picks the platform-appropriate path:\n\n- Windows: `C:\\Program Files\\draw.io\\draw.io.exe`\n- Linux: `/opt/drawio/drawio` or `/opt/draw.io/drawio` (older versions)\n- MacOS: `/Applications/draw.io.app/Contents/MacOS/draw.io`.\n\n### Headless Mode\n- *Formal Name*: `drawio_headless`\n- *Default Value*: `\"auto\"`\n- *Possible Values*: `True`, `False`, or `\"auto\"`\n\nThis config option controls the behaviour of running the Xvfb server. It is\nnecessary because `draw.io` will not work without an X-server, see\n[this issue](https://github.com/jgraph/drawio-desktop/issues/146).\n\nThe `auto` mode will detect whether the program is running in a headless\nenvironment through the `$DISPLAY` environment variable, and act as if it were\nset to `True`. If not running on Linux, or the `$DISPLAY` environment variable\ncontains some value (i.e. running in an X-server on a developer's machine), it\nwill act as it it were set to `False`.\n\nSetting the value to `True` will start a virtual X framebuffer through the\n`Xvfb` command before running any `draw.io` commands, and stop it afterwards.\n\nSetting the value to `False` will run the `draw.io` binary as normal.\n\n### Default Output Format\n- *Formal Name*: `drawio_builder_export_format`\n- *Default Value*: `{}`\n\nThis config option controls the default export file format for each Sphinx\nbuilder. It accepts a dictionary mapping builder names to image formats. The\nbuilder name should match the name of a [Sphinx builder](https://www.sphinx-doc.org/en/master/usage/builders/index.html)\n(e.g., `\"html\"`, `\"latex\"`). Accepted values for the export format are `\"png\"`,\n`\"jpg\"`, `\"svg\"` and `\"pdf\"`. If no format is set for a given builder, its\npreferred image format is used, that is, the first format listed in a builder's\n_supported_image_types_ that draw.io is capable of exporting to (eg. SVG for\nHTML, PDF for LaTeX). \n\n### Default Export Scale\n- *Formal Name*: `drawio_default_export_scale`\n- *Default Value*: `100`\n- *Possible Values*: any positive integer\n\nThis config option sets the default export scale for all diagrams. This scales\nthe size of the diagram. So if you take a diagram that by default would output \na image with a resolution of 50x50 pixels and a scale of 200, you will obtain an\nimage with a resolution that is approximately 100x100 pixels. By default draw.io\n*usually* outputs relatively low resolution images, so this setting can be used\nto remedy that. \n\nThis setting will get automatically overridden if the `scale` is set for a\nindividual diagram in the directive. If either `export-width` or `export-height`\nare set for an image, this option will have no effect on the generated image.\n\n### Default Transparency\n- *Formal Name*: `drawio_default_transparency`\n- *Default Value*: `False`\n- *Possible Values*: `True` or `False`\n\nThis changes the background transparency for diagrams exported in *png* format. \nThis will be overridden if the transparency is set for a individual diagram in\nthe directive. If the output format isn't *png*, it will not affect the image\nexported.\n\n### Disable Verbose Electron\n- *Formal Name*: `drawio_disable_verbose_electron`\n- *Default Value*: `False`\n- *Possible Values*: `True` or `False`\n\nElectron's verbose logging is turned on by default to help troubleshoot certain\nerrors produced by the drawio app, but can be disabled if it causes a logging\nconflict. This option only affects the output when the drawio app errors. See the\n[Electron docs](https://www.electronjs.org/docs/latest/api/command-line-switches#--enable-loggingfile)\nfor more info.\n\n### Disable Shared Memory Usage\n- *Formal Name*: `drawio_disable_dev_shm_usage`\n- *Default Value*: `False`\n- *Possible Values*: `True` or `False`\n\nBy default, Docker runs a container with a `/dev/shm` shared memory space of 64MB.\nThis is typically too small for Chrome (Electron) and will cause Chrome to throw\nan error. Launching the browser with the `--disable-dev-shm-usage` flag will write\nshared memory files into `/tmp` instead of `/dev/shm`.\n\n### Disable GPU\n- *Formal Name*: `drawio_disable_gpu`\n- *Default Value*: `False`\n- *Possible Values*: `True` or `False`\n\nBy default, Chrome (Electron) uses GPU processes which can cause errors when\nrunning in environments that are not set up for it. This option disables those\nGPU processes and uses the CPU instead.\n\n### No Sandbox\n- *Formal Name*: `drawio_no_sandbox`\n- *Default Value*: `False`\n- *Possible Values*: `True` or `False`\n\nThis option may be needed to work in a docker container. You should probably\nonly enable it if you are experiencing issues. See https://github.com/jgraph/drawio-desktop/issues/144 \nfor more info. \n\n## Usage\nThe extension can be used through the `drawio-image` directive. For example:\n```\n.. drawio-image:: example.drawio\n :export-scale: 150\n```\n\nThere's also a `drawio-figure` directive that mimics the `figure` directive:\n```\n.. drawio-figure:: example.drawio\n :format: png\n\n An example diagram\n```\n\nThe directives can be configured with options to control the export of the\ndraw.io diagram to a bitmap or vector image. These options are documented below.\n\nAdditionally, `drawio-image` accepts all of the options supported by the\n[image directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image).\nThese options apply to the image as exported by draw.io. Similarly,\n`drawio-figure` accepts all options supported by the [figure directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure).\n\n### Format\n- *Formal Name*: `:format:`\n- *Default Value*: `\"png\"`\n- *Possible Values*: `\"png\"`, `\"jpg\"`, `\"svg\"` or `\"pdf\"`\n\nThis option controls the output file format of *this specific* directive.\n\n### Page Index\n- *Formal Name*: `:page-index:`\n- *Default Value*: `0`\n- *Possible Values*: any integer\n\nThis option allows you to select a particular page from a draw.io file to\nexport. Note that an invalid page-index will revert to one of the other valid\npages (draw.io binary functionality). `page-name` and `page-index` cannot\ncoexist, if you set both options, an error will be reported.\n\n### Page Name\n- *Formal Name*: `:page-name:`\n- *Default Value*: value of `:page-index:`, else the first page\n- *Possible Values*: any string\n\nThis option allows you to select a particular page by its name from a draw.io\nfile to export. `page-name` and `page-index` cannot coexist, if you set both\noptions, an error will be reported. If `:page-name:` is not found in the draw.io\nfile, an error will be reported too.\n\n### Export Scale\n- *Formal Name*: `:export-scale:`\n- *Default Value*: `drawio_default_export_scale` set in conf.py\n- *Possible Values*: any positive integer\n\nThis scales the size of the output image. So if you take a diagram that by\ndefault would output a image with a resolution of 50x50 pixels and a scale of\n200, you will obtain an image with a resolution that is approximately 100x100 \npixels. By default draw.io *usually* outputs relatively low-resolution images,\nso this setting can be used to remedy that. This overrides the\n`drawio_default_export_scale` set in conf.py for this specific diagram. If\neither `export-width` or `export-height` are set for a given image,\n`export-scale` will have no effect on the generated image.\n\n### Export Width\n- *Formal Name*: `:export-width:`\n- *Possible Values*: any positive integer\n\nThis fits the generated image into the specified width, preserving aspect ratio.\nWhen exporting to a bitmap image, this specifies the width in pixels. For PDF,\na value of 100 corresponds to 1.00 inches.\n\n### Export Height\n- *Formal Name*: `:export-height:`\n- *Possible Values*: any positive integer\n\nThis fits the generated image into the specified height, preserving aspect\nratio. When exporting to a bitmap image, this specifies the height in pixels.\nFor PDF, a value of 100 corresponds to 1.00 inches.\n\n### Transparency\n- *Formal Name*: `:transparency:`\n- *Default Value*: `drawio_default_transparency` set in conf.py\n- *Possible Values*: `\"true\"` or `\"false\"`\n\nThis changes the background transparency for diagrams exported to `png` files.\nWill override `drawio_default_transparency` which was set in conf.py for this\nspecific diagram. If this setting is specified while the output format is not\n`png` it will have no effect on the generated image\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx Extension to include draw.io files",
"version": "0.0.17",
"project_urls": {
"Homepage": "https://github.com/Modelmat/sphinxcontrib-drawio"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34d481b8c94f216ef2fb68475b2f5a2836495e5da4d4ce011b3e41e663b89d1f",
"md5": "8acbaf4b57aac68af21a748b55ea1224",
"sha256": "c42e3fee5398da52836e8ee5c61c2f19bce947abb2d17b857057fb32137c1096"
},
"downloads": -1,
"filename": "sphinxcontrib_drawio-0.0.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8acbaf4b57aac68af21a748b55ea1224",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10727,
"upload_time": "2023-09-12T16:48:50",
"upload_time_iso_8601": "2023-09-12T16:48:50.826148Z",
"url": "https://files.pythonhosted.org/packages/34/d4/81b8c94f216ef2fb68475b2f5a2836495e5da4d4ce011b3e41e663b89d1f/sphinxcontrib_drawio-0.0.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea9b45a4e9f7d5b3f3e8e3fa792f99b20d2f6d337c4b84f9e55044aecf0e60c8",
"md5": "4feddaf2927593e9c6e925993ff097c0",
"sha256": "1a3f82efd1ab4b41d1ee8dd27c296bae0944a10faca3568c462dc6b9a77748f5"
},
"downloads": -1,
"filename": "sphinxcontrib-drawio-0.0.17.tar.gz",
"has_sig": false,
"md5_digest": "4feddaf2927593e9c6e925993ff097c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 25645,
"upload_time": "2023-09-12T16:48:52",
"upload_time_iso_8601": "2023-09-12T16:48:52.488767Z",
"url": "https://files.pythonhosted.org/packages/ea/9b/45a4e9f7d5b3f3e8e3fa792f99b20d2f6d337c4b84f9e55044aecf0e60c8/sphinxcontrib-drawio-0.0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-12 16:48:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Modelmat",
"github_project": "sphinxcontrib-drawio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sphinx",
"specs": [
[
">=",
"2"
]
]
},
{
"name": "wheel",
"specs": [
[
"==",
"0.38.1"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"2.0.0"
]
]
}
],
"lcname": "sphinxcontrib-drawio"
}
JSON
