diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-sphinxcontrib-drawio.spec | 766 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 768 insertions, 0 deletions
@@ -0,0 +1 @@ +/sphinxcontrib-drawio-0.0.16.tar.gz diff --git a/python-sphinxcontrib-drawio.spec b/python-sphinxcontrib-drawio.spec new file mode 100644 index 0000000..5dea3e4 --- /dev/null +++ b/python-sphinxcontrib-drawio.spec @@ -0,0 +1,766 @@ +%global _empty_manifest_terminate_build 0 +Name: python-sphinxcontrib-drawio +Version: 0.0.16 +Release: 1 +Summary: Sphinx Extension to include draw.io files +License: MIT +URL: https://github.com/Modelmat/sphinxcontrib-drawio +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/73/17/c50b51a5336911ddf84dc0182c58b8b7e64d759382d5934e4725fa88c2be/sphinxcontrib-drawio-0.0.16.tar.gz +BuildArch: noarch + +Requires: python3-sphinx + +%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 suitable image format. + +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 removed; the draw.io + diagram is exported to the Sphinx builder's preferred image format (eg. SVG + for HTML, PDF for LaTeX). The *drawio_builder_export_format* configuration + variable allows setting another default export format for each builder. Note + that this can still be overridden for individual `drawio-image` and + `drawio-figure` directives. See below for details. +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](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. + +### 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). + +### 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 + + + + +%package -n python3-sphinxcontrib-drawio +Summary: Sphinx Extension to include draw.io files +Provides: python-sphinxcontrib-drawio +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-sphinxcontrib-drawio +# 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. + +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 removed; the draw.io + diagram is exported to the Sphinx builder's preferred image format (eg. SVG + for HTML, PDF for LaTeX). The *drawio_builder_export_format* configuration + variable allows setting another default export format for each builder. Note + that this can still be overridden for individual `drawio-image` and + `drawio-figure` directives. See below for details. +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](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. + +### 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). + +### 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 + + + + +%package help +Summary: Development documents and examples for sphinxcontrib-drawio +Provides: python3-sphinxcontrib-drawio-doc +%description help +# 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. + +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 removed; the draw.io + diagram is exported to the Sphinx builder's preferred image format (eg. SVG + for HTML, PDF for LaTeX). The *drawio_builder_export_format* configuration + variable allows setting another default export format for each builder. Note + that this can still be overridden for individual `drawio-image` and + `drawio-figure` directives. See below for details. +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image). +- 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](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. + +### 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). + +### 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 + + + + +%prep +%autosetup -n sphinxcontrib-drawio-0.0.16 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-sphinxcontrib-drawio -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Wed May 10 2023 Python_Bot <Python_Bot@openeuler.org> - 0.0.16-1 +- Package Spec generated @@ -0,0 +1 @@ +8663b50d2b41c90c5d1e0b481a05a488 sphinxcontrib-drawio-0.0.16.tar.gz |