Sphinx extension to render the image by script or command
Project description
A sphinx extension to render the image/figure generated by the command body.
- author:
“Yongping Guo”<guoyoooping@163.com>
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for sphinxcontrib-cmd2img-1.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7a63940674252d133aeb1c359be847d327fd482a87e5810d1c57847cd54d7461 |
|
MD5 | 1ec38be65c21ec5dd676f06e4d8103b4 |
|
BLAKE2b-256 | e7874a38bd2bf9028e4d1475669c8860e62a2106677fc3e224114bbba11723a7 |