Sphinx 拡張: sphinxcontrib-nwdiag

sphinxcontrib-nwdiag を利用すると Sphinx の拡張機能としてnwdiag によるネットワーク図を埋め込むことができます。ネットワーク図の埋め込みには `nwdiag ディレクティブを利用します。

.. nwdiag::

    nwdiag {
      network dmz {
          web01;
          web02;
      }
    }

設定

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

インストール

$ sudo easy_install sphinxcontrib-nwdiag

Sphinx の設定

Sphinxcontrib-nwdiag を利用するには conf.py を編集します。extensions 変数に sphinxcontrib.nwdiag を追加し、必要に応じてオプションを記載します。

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

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

利用可能なディレクティブ

.. nwdiag:: [filename]

seqdiag ディレクティブは指定した箇所にネットワーク図を埋め込みます。ネットワークの元となるテキストはファイルもしくはテキストブロックで渡すことができます。ファイルを指定する場合は nwdiag ディレクティブの引数にファイル名を指定します。テキストブロックを指定する場合は nwdiag ディレクティブ以降の行にブロックを記述します。

例:

.. nwdiag:: foobar.diag

.. nwdiag::

   nwdiag {
      // some diagrams are here.
   }

maxwidth オプションを指定すると画像の横幅を調整することができます。maxwidth オプションの引数はピクセル単位で指定します。

例:

.. nwdiag::
   :maxwidth: 240

   nwdiag {
      // some diagrams are here.
   }

バージョン 0.2.0 で追加.

各ノードに対する説明を記載する場合は description 属性と desctable オプションを使用して、ノードの説明表を生成することができます。

入力:

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

利用可能な設定オプション

nwdiag_fontpath

nwdiag で利用する TrueType フォントへのパスを指定します。 nwdiag_fontpath にはパス文字列もしくはパス文字列の配列を指定することができます。複数の環境で Sphinx プロジェクトを共有している場合は、パス文字列の配列を指定することで環境の違いを吸収することができます。

バージョン 0.1.1 で追加.

nwdiag_antialias

nwdiag_antialias は PNG 画像生成時にアンチエイリアス処理を行うかどうかを指定します。 True が指定された場合、アンチエイリアス処理を実行します(初期値: False )。

nwdiag_html_image_format

You can specify image format on converting docs to HTML using nwdiag_html_image_format . nwdiag_html_image_format accepts ‘PNG’ or ‘SVG’ .

nwdiag_tex_image_format

You can specify image format on converting docs to TeX using nwdiag_html_image_format . nwdiag_html_image_format accepts ‘PNG’ or ‘PDF’ .

If you set PDF, you will get clear diagram images as vector format. (*) reportlab is needed .