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

Setting

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

Install

$ pip install sphinxcontrib-nwdiag

Configure Sphinx

To enable this extension, add sphinxcontrib.nwdiag, sphinxcontrib.rackdiag and sphinxcontrib.packetdiag modules to extensions option at 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'

Note

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

Directive

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

Examples:

.. nwdiag:: foobar.diag

.. nwdiag::

   nwdiag {
      // 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 0.8.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:

.. 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"];
      }
   }

Generated:

Name	Description
A	web server01
B	web server02
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.

.. rackdiag:: [filename]

This directive inserts a rack diagram into the document. When filename argument is specified, the extension reads a diagram definitiom from file. In another case, it reads from code block.

Examples:

.. rackdiag:: foobar.diag

.. rackdiag::

   rackdiag {
      // some diagrams are here.
   }

rackdiag directive recognize options same as nwdiag directive.

.. packetdiag:: [filename]

This directive inserts a packet diagram into the document. When filename argument is specified, the extension reads a diagram definitiom from file. In another case, it reads from code block.

Examples:

.. packetdiag:: foobar.diag

.. packetdiag::

   packetdiag {
      // some diagrams are here.
   }

packetdiag directive recognize options same as nwdiag directive.

Configuration File Options

nwdiag_fontpath = str or list of str

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

New in version 0.1.1: nwdiag_fontpath accepts fontpath list

nwdiag_fontmap = str

The path to fontmap definitions.

nwdiag_antialias = bool

Render diagrams in antialias mode or not.

nwdiag_transparency = bool

Render diagrams as transparency or not.

New in version 0.9.0.

nwdiag_html_image_format = "PNG" or "SVG"

The output image format at generating HTML docs.

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

nwdiag_tex_image_format = "PNG" or "PDF"

Deprecated since version 0.8.0: Use nwdiag_latex_image_format option.

Same as “nwdiag_latex_image_format” option.

nwdiag_debug = bool

Enable debug mode of nwdiag.