Metadata-Version: 1.0
Name: sphinxcontrib-cmd2img
Version: 1.0.1
Summary: Sphinx extension to render the image by script or command
Home-page: https://github.com/stathissideris/sphinxcontrib-cmd2img
Author: Yongping Guo
Author-email: guoyoooping@163.com
License: BSD
Description: sphinxcontrib-cmd2img
        *********************
        
        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.
        
        .. _image: http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
        .. _figure: http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure
        
        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:
        
        .. image:: http://ditaa.sourceforge.net/images/first.png
        
        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:
        
        .. image:: http://gnuplot.sourceforge.net/demo_5.2/transparent.2.png
        
        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:
        
        .. image:: https://matplotlib.org/3.2.1/_images/sphx_glr_artists_001.png
        
        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:
        
        .. image:: http://www.imagemagick.org/Usage/basics/properity_option_append.gif
        
        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
        
        .. _ditaa: http://ditaa.sourceforge.net/
        .. _Sphinx: http://sphinx.pocoo.org/
        
        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.
        
Platform: any
