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:
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:
.. cmd2fig:: ditaa :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 :caption: figure 2. illustration for command option. +--------+ +-------+ +-------+ | | --+ ditaa +--> | | | Text | +-------+ |diagram| |Document| |!magic!| | | | {d}| | | | | +---+----+ +-------+ +-------+ : ^ | Lots of work | +-------------------------+
3.2 sphinxcontrib-cmd2img options
- 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
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-0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9b87c72537faa359a647a5f88d43cbbb2010dfb45f22d51a604b7035fe97e900 |
|
MD5 | 4003c88492f9d9fd7ad76152a9f455e2 |
|
BLAKE2b-256 | 3f07c1e7f4933912a77bf456b2c51dd1dd6cea3b0664975df34c5158ce019f3c |