sphinxcontrib-blockdiag

sphinxcontrib-blockdiag is a Sphinx extension for embedding blockdiag diagrams. You can embed block diagrams with the blockdiag directive.

.. blockdiag::

    blockdiag admin {
      top_page -> config -> config_edit -> config_confirm -> top_page;
    }

Setting

You can get archive file at http://bitbucket.org/birkenfeld/sphinx-contrib/

Install

$ pip install sphinxcontrib-blockdiag

Configure Sphinx

To enable this extension, add sphinxcontrib.blockdiag module to extensions option at conf.py.

# Enabled extensions
extensions = ['sphinxcontrib.blockdiag']

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'

Note

If you write documents including multibyte characters, you have to set fontpath to blockdiag_fontpath.

Directive

.. blockdiag:: [filename]

This directive inserts a block diagram into the document. When the filename argument is specified, the extension reads the diagram definition from the specified file. Otherwise, it reads the diagram definition from the code block.

Examples:

.. blockdiag:: foobar.diag

.. blockdiag::

   blockdiag {
      // some diagrams are here.
   }

In addition, the following options are recognized:

alttext

Alternate text: a short description of the diagram, displayed by applications that cannot display diagram.

heightlength

The desired height of the diagram. When the “scale” option is also specified, they are combined. For example, a height of 200px and a scale of 50 is equivalent to a height of 100px with no scale.

widthlength

The width of the diagram. As with “height” above, when the “scale” option is also specified, they are combined.

scaleinteger percentage

The uniform scaling factor of the image. The default is “100%”, i.e. no scaling.

maxwidthlength

Deprecated since version 1.4.0: Use width option.

Same as “width” option.

align“left”, “center” or “right”

The horizontal alignment of the diagram.

captiontext

The caption of the diagram.

desctable :

Description Table: a table that describes each diagram elements (cf. nodes, edges) When this option is specified, Sphinx generates Description Table from diagram, corrects descriptons from description attribute of each node and edges.

Example:

.. blockdiag::
   :desctable:

   blockdiag {
      A -> B -> C;
      A [description = "browsers in each client"];
      B [description = "web server"];
      C [description = "database server"];
   }

Generated:

Name	Description
A	browsers in each client
B	web server
C	database server

figwidth“image”, length

The width of the figure. A special value of “image” is allowed, in which case the included diagram’s actual width is used.

figclasstext

Set a classes attribute value on the figure element.

nametext

Set a names attribute value on the diagram-image element. This allows hyperlink references to the diagram using text as reference name.

classtext

Set a classes attribute value on the diagram-image element.

Configuration File Options

blockdiag_fontpath = str or list of str

The paths to truetype fonts. blockdiag_fontpath option accepts both single path string and list of paths.

New in version 0.1.1: blockdiag_fontpath accepts fontpath list

blockdiag_fontmap = str

The path to fontmap definitions.

blockdiag_antialias = bool

Render diagrams in antialias mode or not.

blockdiag_transparency = bool

Render diagrams as transparency or not.

New in version 1.5.0.

blockdiag_html_image_format = "PNG" or "SVG"

The output image format at generating HTML docs.

blockdiag_latex_image_format = "PNG" or "PDF"

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_tex_image_format = "PNG" or "PDF"

Deprecated since version 1.4.0: Use blockdiag_latex_image_format option.

Same as “blockdiag_latex_image_format” option.

blockdiag_debug = bool

Enable debug mode of blockdiag.