Sphinx 拡張: sphinxcontrib-nwdiag

sphinxcontrib-nwdiag is a Sphinx extension for embedding nwdiag diagrams. You can embed network diagrams with the nwdiag, rackdiag and packetdiag directives.

.. nwdiag::

    nwdiag {
      network dmz {
          web01;
          web02;
      }
    }

インストール・設定

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

インストール

$ pip install sphinxcontrib-nwdiag

Sphinx の設定

sphinxcontrib.nwdiag や sphinxcontrib.rackdiag 、 sphinxcontrib.packetdiag を有効にするには conf.py を以下のように書き換えます。

# Enabled extensions
extensions = ['sphinxcontrib.nwdiag',
              'sphinxcontrib.rackdiag',
              'sphinxcontrib.packetdiag']

# Fontpath for nwdiag series (truetype font)
nwdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'

注釈

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

ディレクティブ

.. nwdiag:: [filename]

This directive inserts a network 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.

例:

.. nwdiag:: foobar.diag

.. nwdiag::

   nwdiag {
      // some diagrams are here.
   }

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

alttext

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

heightlength

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

widthlength

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

scaleinteger percentage

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

maxwidthlength

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

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

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

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

captiontext

図の表題を指定します。

desctable :

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

例:

.. nwdiag::
   :desctable:

   nwdiag {
      network {
        A [address = 192.168.0.1, description = "web server01"];
        B [address = 192.168.0.2, description = "web server02"];
      }
      network {
        A [address = 172.0.0.1];
        C [address = 172.0.0.2, description = "database server"];
      }
   }

生成結果:

Name

Description

A

web server01

B

web server02

C

database server
figwidth"image", length

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

figclasstext

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

nametext

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

classtext

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

.. rackdiag:: [filename]

rackdiag ディレクティブは指定した場所にラック構成図を埋め込みます。filename 引数が指定された場合はそのファイルから、それ以外の場合はテキストブロックからブロック図の定義を読み込みます。

例:

.. rackdiag:: foobar.diag

.. rackdiag::

   rackdiag {
      // some diagrams are here.
   }

rackdiag ディレクティブはオプションとして nwdiag と同じものを指定することができます。

.. packetdiag:: [filename]

packetdiag ディレクティブは指定した場所にパケットヘッダ図を埋め込みます。filename 引数が指定された場合はそのファイルから、それ以外の場合はテキストブロックからブロック図の定義を読み込みます。

例:

.. packetdiag:: foobar.diag

.. packetdiag::

   packetdiag {
      // some diagrams are here.
   }

packetdiag ディレクティブはオプションとして nwdiag と同じものを指定することができます。

設定オプション

nwdiag_fontpath = str or list of str

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

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

nwdiag_fontmap = str

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

nwdiag_antialias = bool

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

nwdiag_transparency = bool

Render diagrams as transparency or not.

バージョン 0.9.0 で追加.

nwdiag_html_image_format = "PNG" or "SVG"

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

nwdiag_latex_image_format = "PNG" or "PDF"

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

nwdiag_tex_image_format = "PNG" or "PDF"

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

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

nwdiag_debug = bool

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