Sphinx Extension to include draw.io files
Project description
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 format suitable for the selected Sphinx builder.
These directives replace the drawio
directive which is now deprecated, and
for which support will be dropped in version 1.0. Deprecation warnings are
output when a drawio
directive is encountered. Please replace these with
drawio-image
orand drawio-figure
, taking into account these differences:
- the drawio_output_format conf.py option has been replaced by the drawio_builder_export_format option, where you can specify the export format for each builder separately.
- the scale, width and height options have been renamed, respectively, to export-scale, export-width and export-height so as not to conflict with the options inherited from the image directive.
- the export-scale option now takes an integer percentage; i.e. a value of 100
means no scaling. This was changed to allow non-integer scaling and offer
consistency with the
scale
option inherited from the image directive. - the drawio_default_scale conf.py option has been replaced by the drawio_default_export_scale option, also accepting a integer percentage value.
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.
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
-
python3 -m pip install sphinxcontrib-drawio
-
In your sphinx config:
extensions = [ "sphinxcontrib.drawio" ]
-
Add the binary to
$PATH
. For Windows addC:\Program Files\draw.io
and on Linux add/opt/draw.io/
. -
(if running headless),
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 gets chosen depending on the OS (Linux, Mac, or Windows) to the default install path of the draw.io program.
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.
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.
Output Format
- Formal Name:
drawio_builder_export_format
- Default Value:
{"html": "svg", "latex": "pdf", "rinoh": "pdf"}
This config option controls the export file format for each Sphinx builder. It
accepts a dictionary mapping builder names to image formats. Accepted values for
the latter are "png"
, "jpg"
, or "svg"
.
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
orFalse
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.
No Sandbox
- Formal Name:
drawio_no_sandbox
- Default Value:
False
- Possible Values:
True
orFalse
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.
These options apply to the image as exported by draw.io. Similarly,
drawio-figure
accepts all options supported by the figure directive.
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. It
provides similar functionality to that of the drawio_builder_export_format
config option (see above) but at an individual image level.
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).
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxcontrib-drawio-0.0.12.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | cb2233ab8fe4e3aaeba16addf879acd7e4f21a515da7aae5b608b9baf9354d83 |
|
MD5 | b2ba964729f53d398fb1071bc1befa7f |
|
BLAKE2b-256 | 882751a1f718d6df8c928abfdea1c17679353eca79b62e1b84fe262c146d5caf |
Hashes for sphinxcontrib_drawio-0.0.12-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6a263c084417a0c68f49eb30e921ff029c917bcfa4ed289c3fb489bfa77bee48 |
|
MD5 | b5c293d0a8931690894d4a28c45f8e2b |
|
BLAKE2b-256 | cc366c7affa08db91282ac62dbc4b68c655cd62438aa85c8aee40fb5b4dc90c3 |