sphinxcontrib-cmd2img 0.4

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:

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 suffix options:

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

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

Another example is gnuplot:

.. cmd2img:: gnuplot

    set y2tics -100, 10
    set ytics nomirror
    plot sin(1/x) axis x1y1, 100*cos(x) axis x1y2

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

.. cmd2img:: convert rose: -duplicate 29 -virtual-pixel Gray -distort SRT '%[fx:360.0*t/n]' -set delay '%[fx:t == 0 ? 240 : 10]' -loop 0 rose.gif

Another example:

.. cmd2img:: dot -T png

    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 --svg
   :caption: figure 2. illustration for command option.

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

3.2 sphinxcontrib-cmd2img options

• suffix:

  specify the output suffix.

• 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:

.. cmd2img:: gnuplot
   :width: 300
   :watermark: text 0,0 "gnuplot test"

    set y2tics -100, 10
    set ytics nomirror
    plot sin(1/x) axis x1y1, 100*cos(x) axis x1y2

5. License

GPLv3

6. Changelog

0.1 Initial upload. 0.2 Correct minor typo