sphinxcontrib-plot 1.0

Sphinx extension to render the image by script or command

A sphinx extension to plot all kind of graph from script or command.

author:

“Yongping Guo”<[e-mail]>

1. Installing and setup

pip install sphinxcontrib-plot

And just add sphinxcontrib.plot to the list of extensions in the conf.py file. For example:

extensions = ['sphinxcontrib.plot']

2. Introduction and examples

In rst we we use image and figure directive to render image/figure. In fact we can plot anything in rst as it was on shell. For examples:

2.1 ditaa example

ditaa is a small command-line utility that can convert diagrams drawn using ascii art (‘drawings’ that contain characters that resemble lines like | / - ), into proper bitmap graphics. We could use the following directive to render the image generated by ditaa:

.. plot:: ditaa
   :caption: figure 1. illustration for ditaa

    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+

Or plot it with parameters:

.. plot:: ditaa --svg
   :caption: figure 2. illustration for ditaa with option

      +--------+   +-------+    +-------+
      |        | --+ ditaa +--> |       |
      |  Text  |   +-------+    |diagram|
      |Document|   |!magic!|    |       |
      |     {d}|   |       |    |       |
      +---+----+   +-------+    +-------+
          :                         ^
          |       Lots of work      |
          +-------------------------+

After convert using ditaa, the above file becomes:

2.2 gnuplot example

Another example is gnuplot.:

.. plot:: gnuplot
    :caption: figure 3. illustration for gnuplot
    :size: 500,300

    set style fill transparent solid 0.5 noborder
    set style function filledcurves y1=0

    Gauss(x,mu,sigma) = 1./(sigma*sqrt(2*pi)) * exp( -(x-mu)**2 / (2*sigma**2) )
    d1(x) = Gauss(x, 0.5, 0.5)
    d2(x) = Gauss(x,  2.,  1.)
    d3(x) = Gauss(x, -1.,  2.)

    set xrange [-5:5]
    set yrange [0:1]
    set key title "Gaussian Distribution"
    set key top left Left reverse samplen 1
    set title "Transparent filled curves"
    plot d1(x) fs solid 1.0 lc rgb "forest-green" title "μ =  0.5 σ = 0.5", \
         d2(x) lc rgb "gold" title "μ =  2.0 σ = 1.0", \
         d3(x) lc rgb "dark-violet" title "μ = -1.0 σ = 2.0"

After convert using gnuplot, the above file becomes:

2.3 python example

Another example is mulplotlib.plot.

.. plot:: python
    :caption: figure 4. illustration for python

    import numpy as np
    import matplotlib.pyplot as plt

    fig = plt.figure()
    fig.subplots_adjust(top=0.8)
    ax1 = fig.add_subplot(211)
    ax1.set_ylabel('volts')
    ax1.set_title('a sine wave')

    t = np.arange(0.0, 1.0, 0.01)
    s = np.sin(2*np.pi*t)
    line, = ax1.plot(t, s, color='blue', lw=2)

    # Fixing random state for reproducibility
    np.random.seed(19680801)

    ax2 = fig.add_axes([0.15, 0.1, 0.7, 0.3])
    n, bins, patches = ax2.hist(np.random.randn(1000), 50,
                                facecolor='yellow', edgecolor='yellow')
    ax2.set_xlabel('time (s)')
    plt.savefig("sphx_glr_artists_001.png")

After conversion using python, we could get the following image:

2.4 graphviz(dot) example

Another example is graphivx(dot), since we want to generate png image, we add the option in the command, it’s dot’s own option:

.. plot:: dot -Tpng
    :caption: illustration for dot

    digraph G {

            subgraph cluster_0 {
                    style=filled;
                    color=lightgrey;
                    node [style=filled,color=white];
                    a0 -> a1 -> a2 -> a3;
                    label = "process #1";
            }

            subgraph cluster_1 {
                    node [style=filled];
                    b0 -> b1 -> b2 -> b3;
                    label = "process #2";
                    color=blue
            }
            start -> a0;
            start -> b0;
            a1 -> b3;
            b2 -> a3;
            a3 -> a0;
            a3 -> end;
            b3 -> end;

            start [shape=Mdiamond];
            end [shape=Msquare];
    }

After convert using dot, the above file becomes:

2.5 convert example

Another example is convert. You can write the command in the commnad line:

.. plot::
:caption: illustration for convert

convert rose:  -fill none -stroke white -draw 'line 5,40 65,5'  rose_raw.png

This is the output:

or you can write most of the command line in the body:

.. plot::
    :caption: illustration for convert

    convert
    -size 140x130 xc:white -stroke black \
    -fill red   -draw "path 'M 60,70 L   60,20   A 50,50 0 0,1 68.7,20.8 Z'" \
    -fill green -draw "path 'M 60,70 L 68.7,20.8 A 50,50 0 0,1 77.1,23.0 Z'" \
    -fill blue  -draw "path 'M 68,65 L 85.1,18.0 A 50,50 0 0,1  118,65   Z'" \
    -fill gold  -draw "path 'M 60,70 L  110,70   A 50,50 0 1,1   60,20   Z'" \
    -fill black -stroke none  -pointsize 10 \
    -draw "text 57,19 '10' text 70,20 '10' text 90,19 '70' text 113,78 '270'" \
    piechart.jpg

2.6 Other applications

In theory, All the command which could generate graph could be used after the directive “..plot::”. Please report it when you found anyone which works or doesn’t work.

3 Options

sphinxcontrib-plot provide some options for easy use.

3.1 command options

First of all, you can add any parameter after the command. sphinxcontrib-plot doesn’t know and interfere with it and only get the graph after it’s executed. for example:

.. plot:: ditaa --no-antialias -s 2
   :caption: figure 1. illustration for ditaa with option.

    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+

3.2 sphinxcontrib-plot options

• size:

  Control the output image size for gnuplot.

• suffix:

  Control the output image format.

• convert:

  After the image is generate, if you’d like to add some watermark, use convert to do that

• show_source:

  for text generated iamge, if the source code is shown.

Besdies that, you can you any options for figure and image.

For example:

.. plot:: gnuplot
    :caption: figure 1. illustration for gnuplot with watermark.
    :convert: -stroke red -strokewidth 2 -fill none -draw "line 100,100
             200, 200"
    :size: 900,600
    :width: 600

    plot [-5:5] (sin(1/x) - cos(x))*erfc(x)

3.2 global options

Please add the following option into you conf.py to designate defualt output file format for different targe.

gnuplot_format = dict(latex=’pdf’, html=’png’)

4. License

GPLv3

5. Changelog

1.0 Initial upload.