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;
    }

インストール・設定

アーカイブファイルは http://bitbucket.org/birkenfeld/sphinx-contrib/ からダウンロードすることができます。

インストール

$ pip install sphinxcontrib-blockdiag

Sphinx の設定

sphinxcontrib.blockdiag を有効にするには conf.py を以下のように書き換えます。

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

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

注釈

日本語を利用する場合は、 blockdiag_fontpath を設定する必要があります。

ディレクティブ

.. 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.

例:

.. blockdiag:: foobar.diag

.. blockdiag::

   blockdiag {
      // some diagrams are here.
   }

blockdiag ディレクティブには以下のオプションを指定することができます。

alttext

図を表示することができないアプリケーションが用いる代替テキスト(図の説明文)です。

heightlength

図の高さを指定します。"scale" オプションと同時に指定された場合、掛けあわせた結果が利用されます。例えば height オプションに 200px 、 scale オプションに 50% が指定された場合、図の高さとして 100px が指定されたものと解釈します。

widthlength

図の幅を指定します。 height オプションと同様に、 scale オプションと同時に指定された場合、掛けあわせた結果が利用されます。

scaleinteger percentage

図の表示倍率を指定します。デフォルトでは 100%、つまりそのままの大きさで埋め込まれます。

maxwidthlength

バージョン 1.4.0 で非推奨: width オプションを使ってください。

"width" オプションと等価です。

align"left", "center" or "right"

図の表示位置を指定します。

captiontext

図の表題を指定します。

desctable :

図の要素(ノード、エッジなど)の説明表を生成します。desctable オプションが指定された場合、各要素の description 属性から要素の説明文を抜き出し、図と共に説明表を生成します。

例:

.. blockdiag::
   :desctable:

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

生成結果:

Name

Description

A

browsers in each client

B

web server

C

database server
figwidth"image", length

figure 要素の幅を指定します。"image" を指定した場合は図のサイズが利用されます。

figclasstext

figure 要素の classes 属性を指定します。

nametext

図の names 属性を指定します。設定した名前を使うことでドキュメント内から図へのハイパーリンクを作ることができます。

classtext

図の classes 属性を指定します。

設定オプション

blockdiag_fontpath = str or list of str

TrueType フォントファイルへのパスを指定します。blockdiag_fontpath オプションにはファイル名(文字列)もしくはファイル名の配列を指定することができます。

バージョン 0.1.1 で追加: 配列によるパス指定に対応しました。

blockdiag_fontmap = str

フォント定義ファイルへのパスを指定します。

blockdiag_antialias = bool

図の描画の際にアンチエイリアスを行うかを指定します。

blockdiag_transparency = bool

Render diagrams as transparency or not.

バージョン 1.5.0 で追加.

blockdiag_html_image_format = "PNG" or "SVG"

HTML 文書生成の際の画像出力フォーマットを指定します。

blockdiag_latex_image_format = "PNG" or "PDF"

LaTeX 経由で PDF 文書を生成する際の画像出力フォーマットを指定します。"PDF" フォーマットで画像を出力するとベクター形式の画像を得ることができます。なお、その場合は reportlab のインストールが必要です。

blockdiag_tex_image_format = "PNG" or "PDF"

バージョン 1.4.0 で非推奨: blockdiag_latex_image_format オプションを使ってください。

"blockdiag_latex_image_format" オプションと等価です。

blockdiag_debug = bool

デバッグモードを有効にします。