sphinxcontrib-cmd2img 1.0.2

Sphinx extension to render the image by script or command

A sphinx extension to render the image/figure generated by the command body.

author:

“Yongping Guo”<[e-mail]>

1. Installing and setup

pip install sphinxcontrib-cmd2img

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

extensions = ['sphinxcontrib.cmd2img']

2. Introduction and examples

In rst we we use image and figure directive to render image/figure in the target html document, which give us much convenience. In fact we could rending more things than that.

Sometime some command would convert or generate a image, we would like to render it efficiently and directly, for example:

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:

.. cmd2img:: ditaa

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

Or use the following directive to render it as a figure, for a figure, we can add a caption, to render it as .svg file, we add –svg in the command line:

.. cmd2fig:: ditaa --svg
   :caption: figure 1. An example to use ditaa to render a figure

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

After conversion using ditaa, the above file becomes:

2.2 gnuplot example

Another example is gnuplot:

.. cmd2img:: gnuplot
    :image: transparent.2.png

    set terminal pngcairo  transparent enhanced font "arial,8" fontscale 1.0 size 512, 280
    set output 'transparent.2.png'
    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 conversion using gnuplot, the above file becomes:

2.3 python example

Another example is python:

.. cmd2img:: python3
    :image: sphx_glr_artists_001.png
    :caption: 例子

    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 python3, the above file becomes:

2.4 convert example

Another example is convert, it will be rendered as a gif in the target:

.. cmd2img:: convert rose:  -set option:myinfo 'I love IM!'  label:'== %[myinfo] ==' -gravity center -append properity_option_append.gif
    :image: properity_option_append.png

After conversion using convert, the above file becomes:

2.5 dot example

Another example:

.. cmd2img:: dot -Tpng

    digraph example {
        a [label="sphinx", href="http://www.sphinx-doc.org/en/master/usage/extensions/index.html", target="_top"];
        b [label="other"];
        a -> b;
    }

3 Options

sphinxcontrib-cmd2img provide some options for easy use.

3.1 command options

For command options, you should add it right after the command, for example:

.. cmd2fig:: ditaa --no-antialias
   :caption: figure 2. illustration for command option.

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

3.2 sphinxcontrib-cmd2img options

• image:

  For those command whose the output name is embeded in the body, Users should copy the name here.

• show_source:

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

• watermark:

  Add water mark in the image

• gravity:

  watermark gravity, see detail imagematick command convert -draw

• location:

  watermark location, see detail imagematick command convert -draw

• fill:

  watermark contention, see detail imagematick command convert -draw

• pointsize:

  watermark pointsize, see detail imagematick command convert -draw

• font:

  watermark font, see detail imagematick command convert -draw

For example:

.. cmd2fig:: gnuplot
    :caption: 在plot 命令里指定范围
    :image: gnuplot_test.png
    :width: 600

    set output 'gnuplot_test.png'
    set terminal pngcairo
    plot [-5:5] (sin(1/x) - cos(x))*erfc(x)

5. License

GPLv3

6. Changelog

0.1 Initial upload. 0.2 Correct minor typo 1.0 Upgrade to 1.0, bug fix: If there is change of the script, it doesn’t generate a new image. 1.0.2 Bug fix: When copy file error, shouldn’t break the following process.