From ce067ce61e4f966d8694408e5e795d8fd18eee9f Mon Sep 17 00:00:00 2001 From: James Knight Date: Sat, 31 Aug 2024 11:22:14 -0400 Subject: [PATCH] blockdiag-sphinxcontrib: add blockdiag_image_format configuration Adding some initial documentation of the `blockdiag_image_format` configuration. Signed-off-by: James Knight --- sources/en/blockdiag/sphinxcontrib.rst | 46 +++++++++++++++++++++----- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/sources/en/blockdiag/sphinxcontrib.rst b/sources/en/blockdiag/sphinxcontrib.rst index a88afad..17323ff 100644 --- a/sources/en/blockdiag/sphinxcontrib.rst +++ b/sources/en/blockdiag/sphinxcontrib.rst @@ -178,24 +178,52 @@ Configuration File Options .. versionadded:: 1.5.0 -.. confval:: blockdiag_html_image_format = "PNG" or "SVG" +.. confval:: blockdiag_image_format = dict - The output image format at generating HTML docs. + The output image format to use. For example: -.. confval:: blockdiag_latex_image_format = "PNG" or "PDF" + .. code-block:: python - The output image format at generating PDF docs (through LaTeX). - When a value of "PDF" is specified, you can get clear diagram images. - In which case, reportlab_ library is required. + blockdiag_image_format = { + 'html': 'SVG', # PNG, SVG + 'latex': 'PDF', # PDF, PNG + '*': 'PNG', + } + + In this example, when building with an ``html`` builder, SVG images will + be generated. Users can configure specific image formats for the builder + format they desire. To define a fallback image format for other builder + formats, the ``*`` key can be used. + + Supported image formats include ``PNG``, ``SVG`` and ``PDF``. Note + that not all builders can support each image format type. By default, + the ``PNG`` format is used. When using the ``PDF`` format, reportlab_ + library is required. .. _reportlab: https://pypi.python.org/pypi/reportlab -.. confval:: blockdiag_tex_image_format = "PNG" or "PDF" + .. versionadded:: 2.1.0 + +.. confval:: blockdiag_html_image_format = str + + .. deprecated:: 2.1.0 + Use ``blockdiag_image_format`` option. + + Same as the "blockdiag_image_format" option for an ``html`` format. + +.. confval:: blockdiag_latex_image_format = str + + .. deprecated:: 2.1.0 + Use ``blockdiag_image_format`` option. + + Same as the "blockdiag_image_format" option for a ``latex`` format. + +.. confval:: blockdiag_tex_image_format = str .. deprecated:: 1.4.0 - Use ``blockdiag_latex_image_format`` option. + Use ``blockdiag_image_format`` option. - Same as "blockdiag_latex_image_format" option. + Same as the "blockdiag_image_format" option for a ``latex`` format. .. confval:: blockdiag_debug = bool