Metadata-Version: 1.0
Name: sphinxcontrib-plot
Version: 1.0
Summary: Sphinx extension to render the image by script or command
Home-page: https://github.com/stathissideris/sphinxcontrib-plot
Author: Yongping Guo
Author-email: guoyoooping@163.com
License: GPLv3
Description: sphinxcontrib-plot
        *********************
        
        A sphinx extension to plot all kind of graph from script or command.
        
        :author: "Yongping Guo"<guoyoooping@163.com>
        
        1. Installing and setup
        =======================
        
        pip install sphinxcontrib-plot
        
        And just add ``sphinxcontrib.plot`` to the list of extensions in the
        ``conf.py`` file. For example::
        
            extensions = ['sphinxcontrib.plot']
        
        2. Introduction and examples
        ============================
        
        In rst we we use `image`_ and `figure`_ directive to render image/figure. In
        fact we can plot anything in rst as it was on shell. For examples:
        
        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::
        
            .. plot:: ditaa
               :caption: figure 1. illustration for ditaa
        
                +--------+   +-------+    +-------+
                |        | --+ ditaa +--> |       |
                |  Text  |   +-------+    |diagram|
                |Document|   |!magic!|    |       |
                |     {d}|   |       |    |       |
                +---+----+   +-------+    +-------+
                    :                         ^
                    |       Lots of work      |
                    +-------------------------+
        
        Or plot it with parameters::
        
            .. plot:: ditaa --svg
               :caption: figure 2. illustration for ditaa with option
        
                  +--------+   +-------+    +-------+
                  |        | --+ ditaa +--> |       |
                  |  Text  |   +-------+    |diagram|
                  |Document|   |!magic!|    |       |
                  |     {d}|   |       |    |       |
                  +---+----+   +-------+    +-------+
                      :                         ^
                      |       Lots of work      |
                      +-------------------------+
        
        After convert using ditaa, the above file becomes:
        
        .. image:: http://ditaa.sourceforge.net/images/first.png
        
        2.2 gnuplot example
        -------------------
        
        Another example is gnuplot.::
        
            .. plot:: gnuplot
                :caption: figure 3. illustration for gnuplot
                :size: 500,300
        
                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 convert using gnuplot, the above file becomes:
        
        .. image:: http://gnuplot.sourceforge.net/demo_5.2/transparent.2.png
        
        2.3 python example
        ------------------
        
        Another example is mulplotlib.plot. ::
        
            .. plot:: python
                :caption: figure 4. illustration for python
        
                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 python, we could get the following image:
        
        .. image:: https://matplotlib.org/3.2.1/_images/sphx_glr_artists_001.png
        
        2.4 graphviz(dot) example
        --------------------------
        
        Another example is graphivx(dot), since we want to generate png image, we add
        the option in the command, it's dot's own option::
        
            .. plot:: dot -Tpng
                :caption: illustration for dot
        
                digraph G {
        
                        subgraph cluster_0 {
                                style=filled;
                                color=lightgrey;
                                node [style=filled,color=white];
                                a0 -> a1 -> a2 -> a3;
                                label = "process #1";
                        }
        
                        subgraph cluster_1 {
                                node [style=filled];
                                b0 -> b1 -> b2 -> b3;
                                label = "process #2";
                                color=blue
                        }
                        start -> a0;
                        start -> b0;
                        a1 -> b3;
                        b2 -> a3;
                        a3 -> a0;
                        a3 -> end;
                        b3 -> end;
        
                        start [shape=Mdiamond];
                        end [shape=Msquare];
                }
        
        After convert using dot, the above file becomes:
        
        .. image:: http://www.graphviz.org/Gallery/directed/cluster.png
        
        
        2.5 convert example
        -------------------
        
        Another example is convert. You can write the command in the commnad line::
        
            .. plot::
            :caption: illustration for convert
        
            convert rose:  -fill none -stroke white -draw 'line 5,40 65,5'  rose_raw.png
        
        This is the output:
        
        .. image:: https://legacy.imagemagick.org/Usage/draw/rose_raw.png
        
        or you can write most of the command line in the body::
        
            .. plot::
                :caption: illustration for convert
        
                convert
                -size 140x130 xc:white -stroke black \
                -fill red   -draw "path 'M 60,70 L   60,20   A 50,50 0 0,1 68.7,20.8 Z'" \
                -fill green -draw "path 'M 60,70 L 68.7,20.8 A 50,50 0 0,1 77.1,23.0 Z'" \
                -fill blue  -draw "path 'M 68,65 L 85.1,18.0 A 50,50 0 0,1  118,65   Z'" \
                -fill gold  -draw "path 'M 60,70 L  110,70   A 50,50 0 1,1   60,20   Z'" \
                -fill black -stroke none  -pointsize 10 \
                -draw "text 57,19 '10' text 70,20 '10' text 90,19 '70' text 113,78 '270'" \
                piechart.jpg
        
        .. image:: https://legacy.imagemagick.org/Usage/draw/piechart.jpg
        
        2.6 Other applications
        ----------------------
        
        In theory, All the command which could generate graph could be used after the
        directive "..plot::". Please report it when you found anyone which works or
        doesn't work.
        
        3 Options
        ===========
        
        sphinxcontrib-plot provide some options for easy use.
        
        3.1 command options
        -------------------
        
        First of all, you can add any parameter after the command. sphinxcontrib-plot
        doesn't know and interfere with it and only get the graph after it's executed.
        for example::
        
            .. plot:: ditaa --no-antialias -s 2
               :caption: figure 1. illustration for ditaa with option.
        
                +--------+   +-------+    +-------+
                |        | --+ ditaa +--> |       |
                |  Text  |   +-------+    |diagram|
                |Document|   |!magic!|    |       |
                |     {d}|   |       |    |       |
                +---+----+   +-------+    +-------+
                    :                         ^
                    |       Lots of work      |
                    +-------------------------+
        
        3.2 sphinxcontrib-plot options
        ---------------------------------
        
            * :size: Control the output image size for gnuplot.
            * :suffix: Control the output image format.
            * :convert: After the image is generate, if you'd like to add some watermark, use convert to do that
            * :show_source: for text generated iamge, if the source code is shown. 
        
        Besdies that, you can you any options for figure and image.
        
        For example::
        
            .. plot:: gnuplot
                :caption: figure 1. illustration for gnuplot with watermark.
                :convert: -stroke red -strokewidth 2 -fill none -draw "line 100,100
                         200, 200"
                :size: 900,600
                :width: 600
        
                plot [-5:5] (sin(1/x) - cos(x))*erfc(x)
        
        3.2 global options
        ---------------------------------
        
        Please add the following option into you conf.py to designate defualt output
        file format for different targe.
        
            gnuplot_format = dict(latex='pdf', html='png')
        
        4. License
        ==========
        
        GPLv3
        
        .. _ditaa: http://ditaa.sourceforge.net/
        .. _image: http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
        .. _figure: http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure
        
        5. Changelog
        ============
        
        1.0 Initial upload.
        
Platform: any
