Sphinx nwdiag Extension

2.0.0 verified Fri May 01 auth: no python maintenance

Sphinx extension to embed nwdiag (network diagram) diagrams using the blockdiag family. Version 2.0.0 released January 2018; maintained in maintenance mode. Supports Python 2.7+ and 3.x.

pip install sphinxcontrib-nwdiag

Common errors

error Extension 'sphinxcontrib.nwdiag' has no setup() function ↓

cause Wrong import path in extensions list (used dotted module instead of plain name).

fix

Use 'sphinxcontrib.nwdiag' as the extension name in conf.py extensions list.

error Could not render nwdiag: blockdiag not installed ↓

cause Missing required runtime dependency.

fix

pip install blockdiag nwdiag

Warnings

broken Sphinx 4.0+ drops Python 2.7/3.5 support; sphinxcontrib-nwdiag requires blockdiag and nwdiag which may have compatibility issues with newer Sphinx. ↓

fix Upgrade to 2.0.0 and pin Sphinx < 4.0 if necessary.

gotcha The nwdiag directive does not work with Sphinx's 'dirhtml' builder (creates nested directories). Use 'html' builder instead. ↓

fix Set 'html' builder in conf.py: html_builder = 'html'

deprecated Python 2.7 support is deprecated. blockdiag and nwdiag libraries no longer receive updates for Python 2. ↓

fix Use Python 3.5+.

Imports

setup
wrong
```
from sphinxcontrib.nwdiag import nwdiag
```
correct
```
from sphinxcontrib import nwdiag
```
Extension uses setup() function; register via extensions list.

Quickstart

Add extension to conf.py and use nwdiag directive in reStructuredText.

# conf.py
extensions = ['sphinxcontrib.nwdiag']

# index.rst
.. nwdiag::

   nwdiag {
     network dmz {
         address = "210.x.x.x/24"
         web01 [address = "210.x.x.1"];
         web02 [address = "210.x.x.2"];
     }
     network internal {
         web01;
         web02;
         db01;
         db02;
     }
   }