modelmat/sphinxcontrib-drawio
Fork: 17 Star: 34 (更新于 1970-01-01 00:00:00)
license: MIT
Language: Python .
Sphinx extension for including draw.io files.
最后发布版本: 0.0.17 ( 2023-09-13 01:08:09)
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.
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, add:
extensions = [ "sphinxcontrib.drawio" ]
-
Add the draw.io binary to
$PATH
. See Options: Binary Path for more details and alternative solutions. -
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.
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
(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
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.
Disable Verbose Electron
-
Formal Name:
drawio_disable_verbose_electron
-
Default Value:
False
-
Possible Values:
True
orFalse
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 for more info.
Disable Shared Memory Usage
-
Formal Name:
drawio_disable_dev_shm_usage
-
Default Value:
False
-
Possible Values:
True
orFalse
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
orFalse
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
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.
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
最近版本更新:(数据更新于 1970-01-01 00:00:00)
2023-09-13 01:08:09 0.0.17
2022-06-05 15:15:14 0.0.16
2022-05-10 11:13:35 0.0.15
2020-05-06 05:31:40 0.0.7
主题(topics):
drawio, sphinx, sphinx-extension
modelmat/sphinxcontrib-drawio同语言 Python最近更新仓库
2024-11-06 03:34:16 home-assistant/core
2024-11-05 16:16:26 Guovin/TV
2024-11-05 15:03:24 Cinnamon/kotaemon
2024-11-04 23:11:11 DS4SD/docling
2024-11-04 10:56:18 open-compass/opencompass
2024-11-04 08:51:21 yt-dlp/yt-dlp