o
    :ήcP                     @   sP  d Z ddlZddlZddlZddlZddlZddlZddlZddlZ	ddl
Z
e
d ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd	lmZ d
ZdZdZdZdZdZG dd de Z!dd Z"dd Z#dd Z$d0ddZ%dd Z&dd Z'dd Z(d d! Z)d"d# Z*d$d% Z+d&d' Z,d(d) Z-d*d+ Z.d,d- Z/d.d/ Z0dS )1a  
Example generation from python files.

Generate the rst files for the examples by iterating over the python
example files. Files that generate images should start with 'plot'.

To generate your own examples, add this extension to the list of
``extensions``in your Sphinx configuration file. In addition, make sure the
example directory(ies) in `plot2rst_paths` (see below) points to a directory
with examples named `plot_*.py` and include an `index.rst` file.

This code was adapted from scikit-image, which took it from scikit-learn.

Options
-------
The ``plot2rst`` extension accepts the following options:

plot2rst_paths : length-2 tuple, or list of tuples
    Tuple or list of tuples of paths to (python plot, generated rst) files,
    i.e. (source, destination).  Note that both paths are relative to Sphinx
    'source' directory. Defaults to ('../examples', 'auto_examples')

plot2rst_rcparams : dict
    Matplotlib configuration parameters. See
    https://matplotlib.org/tutorials/introductory/customizing.html for details.

plot2rst_default_thumb : str
    Path (relative to doc root) of default thumbnail image.

plot2rst_thumb_shape : float
    Shape of thumbnail in pixels. The image is resized to fit within this shape
    and the excess is filled with white pixels. This fixed size ensures that
    that gallery images are displayed in a grid.

plot2rst_plot_tag : str
    When this tag is found in the example file, the current plot is saved and
    tag is replaced with plot path. Defaults to 'PLOT2RST.current_figure'.


Suggested CSS definitions
-------------------------

    div.body h2 {
        border-bottom: 1px solid #BBB;
        clear: left;
    }

    /*---- example gallery ----*/

    .gallery.figure {
        float: left;
        margin: 1em;
    }

    .gallery.figure img{
        display: block;
        margin-left: auto;
        margin-right: auto;
        width: 200px;
    }

    .gallery.figure .caption {
        width: 200px;
        text-align: center !important;
    }

    NAgg)io)	transform)dtype_range)Notebook)publish_parts)PythonDomainz;
.. literalinclude:: {src_name}
    :lines: {code_start}-

z^

**Python source code:** :download:`download <{0}>`
(generated using ``skimage`` |version|)

z\

**IPython Notebook:** :download:`download <{0}>`
(generated using ``skimage`` |version|)

z"
.. toctree::
   :hidden:

   %s

z*
.. image:: images/%s
    :align: center

zm
.. figure:: %(thumb)s
   :figclass: gallery
   :target: ./%(source)s.html

   :ref:`example_%(link_name)s`

c                       st   e Zd ZdZdd Zedd Zedd Zdd	 Zd
d Z	dd Z
dd Z fddZ fddZdd Z  ZS )Pathz6Path object for manipulating directory and file paths.c                 C   s   t | |S N)str__new__)selfpath r   7/tmp/pip-target-vg8gfxp4/lib/python/doc/ext/plot2rst.pyr         zPath.__new__c                 C      t j| S r
   )osr   isdirr   r   r   r   r      s   z
Path.isdirc                 C   r   )zReturn True if path exists)r   r   existsr   r   r   r   r      s   zPath.existsc                 G   s   |  tjj| g|R  S )z=Join paths. `p` prefix prevents confusion with string method.)	__class__r   r   join)r   argsr   r   r   pjoin      z
Path.pjoinc                    s    fddt j D S )z>Split paths. `p` prefix prevents confusion with string method.c                    s   g | ]}  |qS r   r   .0pr   r   r   
<listcomp>   s    zPath.psplit.<locals>.<listcomp>)r   r   splitr   r   r   r   psplit   r   zPath.psplitc                 C   s   | j s
t|  d S d S r
   )r   r   makedirsr   r   r   r   r#      s   zPath.makedirsc                 C   s
   t | S r
   )r   listdirr   r   r   r   r$         
zPath.listdirc                    s   |  tt| j|i |S r
   )r   superr	   format)r   r   kwargsr   r   r   r'      s   zPath.formatc                    s   |  tt| |S r
   )r   r&   r	   __add__r   otherr   r   r   r)      s   zPath.__add__c                 C   s
   |  |S r
   )r)   r*   r   r   r   __iadd__   r%   zPath.__iadd__)__name__
__module____qualname____doc__r   propertyr   r   r   r"   r#   r$   r'   r)   r,   __classcell__r   r   r   r   r	      s    

r	   c                 C   sd   |  dt | ddd | di d | dd d | ddd | d	d
d | ddd d S )Nzbuilder-initedplot2rst_paths)z../examplesauto_examplesTplot2rst_rcparamsplot2rst_default_thumbplot2rst_thumb_shape)   i,  plot2rst_plot_tagzPLOT2RST.current_figureplot2rst_index_nameindex)connectgenerate_example_galleriesadd_config_value)appr   r   r   setup   s   r@   c                 C   s   | j j}t|jtr|jd |_n|j|_ttj	| j j
}t|jtr*|jg|_|jD ]}dd |D \}}||}||}t||| q-d S )Nr   c                 S   s   g | ]}t |qS r   )r	   r   r   r   r   r       s    z.generate_example_galleries.<locals>.<listcomp>)builderconfig
isinstancesource_suffixlistsource_suffix_strr	   r   r   abspathsrcdirr3   tupler   generate_examples_and_gallery)r?   cfgdoc_srcsrc_dest	plot_pathrst_pathexample_dirrst_dirr   r   r   r=      s   



r=   c              	   C   s   | j s
td|  dS |  t|d|j d7}t|| || t|  D ]}| |}|j	rC||}|  t||||dd q'|
  W d   dS 1 sSw   Y  dS )zCGenerate rst from examples and create gallery to showcase examples.zNo example directory found atNr;   w   )depth)r   printr#   openr   rF   write_gallerysortedr$   r   flush)rP   rQ   rK   gallery_indexdexample_subrst_subr   r   r   rJ      s   



"rJ   c              	   C   s  |j |j }||}tj|s+t| td td||f  td td dS t|}| }W d   n1 s>w   Y  | 	d|  |
  dd t| tdD }	d	d |	D }
|d
krktd}n| | d }td|d }d| }| 	t|||
   |	D ]j}z	t|||| W n! ty   td td||f  td t  td Y qw ||}|tjjd}|dr|dd }i }|d|dd d |d< ||dd  |d< ||d< | 	t|  qdS )a  Generate the rst files for an example directory, i.e. gallery.

    Write rst files from python examples and add example links to gallery.

    Parameters
    ----------
    gallery_index : file
        Index file for plot gallery.
    src_dir : 'str'
        Source directory for python examples.
    rst_dir : 'str'
        Destination directory for rst files generated from python examples.
    cfg : config object
        Sphinx config object created by Sphinx.
    P________________________________________________________________________________z,Example directory %s does not have a %s filezSkipping this directoryNz

%s

c                 S   s   g | ]	}| d r|qS )py)endswith)r   fnamer   r   r   r          
z!write_gallery.<locals>.<listcomp>)keyc                 S   s   g | ]}|d d qS )Nr   )r   exr   r   r   r      s    r    /z
   %szException raised while running:z%s in %sz<~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~_z._   zimages/thumbrd   .pngthumbsource	link_name)r:   rF   r   r   r   r   rU   rV   readwriter#   rX   r$   _plots_firstr	   r"   r   TOCTREE_TEMPLATEwrite_example	Exception	traceback	print_excreplacesep
startswithGALLERY_IMAGE_TEMPLATE)rZ   src_dirrQ   rK   rT   
index_namegallery_templatefgallery_descriptionexamplesex_namessub_dirsub_dir_listjoinersrc_namerm   infor   r   r   rW      sZ   





rW   c                 C   s    |  dr
| dsd|  S | S )zBDecorate filename so that examples with plots are displayed first.plot.pyzz)rx   r`   )ra   r   r   r   rp   %  s   rp   c           0         st  |  d }|dks|dkrtd}n|d7 }|| }|| }t|| |d}|d}|d}	|  |  |	  tj| d	 }
||
d
 }tj| \}}|| j	 }|	|d }t
||ru|jru|jrudS td|  t|}|d	 d dr|d	 d||   }t||| \}}t fdd|D }|rd||g}n:dd |D d	 }|\}\}}}t|}dd |D }|}|t|7 }|d|7 }t| |d}|tjd8i |7 }|t| 7 }| dd}d| }|t|7 }t|d}|| W d   n	1 sw   Y  || dd d }||d	 d} | jrCt| }!t |!| j! |js] j"du rVtd td nt# j"| t$ }"t%j&' }#dd d |#D }$t()d!}%t()d"}&dd#d |D }'t(*|%|'}(|D ]\})}*}|)d$kr|"j+|d$d% q|d&r|d'd}d(}+n|d)d}d*}+|+s|d+d,}|d-d.}t(,|&d/|}|d0d}|- sؐq|$| .d}dd1d |/dD }|(D ]\},}-d2|- d3}.|.|v r||.|.dd }qt0|d4d5d6 }/|"j+|/d7d% qt|d}||"1  W d   dS 1 s3w   Y  dS )9aj  Write rst file from a given python example.

    Parameters
    ----------
    src_name : str
        Name of example file.
    src_dir : 'str'
        Source directory for python examples.
    rst_dir : 'str'
        Destination directory for rst files generated from python examples.
    cfg : config object
        Sphinx config object created by Sphinx.
    .r   rf   rh   imagesrk   notebookr   z_{0}.pngz.ipynbNzplot2rst: %sri   z#!z.. _example_%s:

c                 3   s    | ]
} j |d  v V  qdS )ri   N)r9   r   brK   r   r   	<genexpr>a  s    z write_example.<locals>.<genexpr>c                 S   s   g | ]
}|d  dkr|qS )r   textr   r   r   r   r   r    f  s    z!write_example.<locals>.<listcomp>c                 S   s   g | ]	}t |d  qS )rg   )IMAGE_TEMPLATElstrip)r   r}   r   r   r   r    i  s    )r   
code_startr   z./notebook/rR   rd   rj   rg   z:WARNING: No plots found and default thumbnail not defined.z7Specify 'plot2rst_default_thumb' in Sphinx config file.
c                 s   s    | ]	}d | dV  qdS )z.. role:: py:z
(literal)
Nr   )r   roler   r   r   r     s    z#
(\.\. \[(\d+)\].*(?:
[ ]{7,8}.*)+)z:math:`(.*?)`c                 s   s"    | ]\}}}|d kr|V  qdS )codeNr   )r   	cell_typerh   contentr   r   r   r     s    r   )r   rzr"""Fz"""T\z\\z.. seealso::z**See also:**z$\1$z	.. math::c                 S   s   g | ]	}| d s|qS )z.. image)rx   )r   liner   r   r   r      rb   [z]_html)writer_name	html_bodymarkdownr   )2r"   r	   r   shutilcopyfiler#   r   r   splitextrF   _plots_are_currentr   rU   split_code_and_text_blocksrx   popprocess_blocksanyr   save_all_figuresevaldictLITERALINCLUDEr'   	CODE_LINKrv   NOTEBOOK_LINKrV   ro   r   r   imreadsave_thumbnailr7   r6   copyr   r   roleskeysrecompilefindalladd_cellsubstriprstripr!   r   json)0r   rz   rQ   rK   last_dirsrc_pathexample_file	image_dir	thumb_dirnotebook_dirbase_image_name
image_pathbasenamepy_extrO   notebook_pathblocksrst_linkfigure_listrsthas_inline_plotsexample_rstfirst_text_blocklabelstartendr   
rst_blocks	code_infoipnotebook_namer}   
thumb_pathfirst_image_filefirst_imagenbsphinx_rolespreamble
ref_regexpmath_role_regexpr   
referencesr   rh   escaped	referenceref_idref_tagr   r   r   r   rr   ,  s   















$rr   c           
      C   s   t dd t|| jD }|t| jdd  t}t| |}t	| jdkr1|| jd f }t
|jj d }|tj||jd }|d |d  d }|d |d  d }	|||||d  |	|	|d  f< t|| dS )	zSave image as a thumbnail with the specified shape.

    The image is first resized to fit within the specified shape and then
    centered in an array of the specified shape before saving.
    c                 s   s     | ]\}}t || V  qd S r
   )float)r   w_1w_2r   r   r   r     s    z!save_thumbnail.<locals>.<genexpr>Nri      rS   )dtyper   )minzipshapenpasarrayastypeintr   resizelenr   r   typeonesr   imsave)
imager   r   rescalesmall_shapesmall_imagebackground_valuerk   ijr   r   r   r     s   $r   c                 C   s,   t |d}|j pt|t| k}| S )NrS   )r	   r'   r   	_mod_time)r   r   r   needs_replotr   r   r   r     s
   r   c                 C   s   t | jS r
   )r   statst_mtime)	file_pathr   r   r   r     r   r   c                 C   s   t | \}}t| }| }W d   n1 sw   Y  t|t|d}g }t|dd |dd }t|D ]%\}\}	}
||v rFdnd}d||	d |
d  }|	||	|
f|f q:|S )a)  Return list with source file separated into code and text blocks.

    Returns
    -------
    blocks : list of (label, (start, end+1), content)
        List where each element is a tuple with the label ('text' or 'code'),
        the (start, end+1) line numbers, and content string of block.
    Nri   r   rS   r   r   rf   )
get_block_edgesrV   	readlinesr   aranger   r   	enumerater   append)source_fileblock_edgesidx_first_text_blockr}   source_linesidx_text_blockr   slice_rangesr   r   r   block_labelr   r   r   r   r     s   	

r   c                 C   s   g }t | 2}t|j}|D ]!}|\}}\}}\}	}
}tj| dkr0|dkr0|||	d f qW d   n1 s;w   Y  d}|d dksP|dd d}|d |	ks[||	 ||fS )a  Return starting line numbers of code and text blocks

    Returns
    -------
    block_edges : list of int
        Line number for the start of each block. Note the
    idx_first_text_block : {0 | 1}
        0 if first block is text then, else 1 (second block better be text).
    STRINGr   rS   Nr   )	rV   tokenizegenerate_tokensreadlinetokentok_nameextendinsertr  )r  r  r}   
token_itertoken_tuplet_idt_strsrowscolerowecolsrc_liner  r   r   r   r     s"   


r   c                    s  |  \}}|dsg dfS |j  fddt| D }|  \}}g }	t  tj|j t	d i }
g }d}t| D ]F\}\}}}|dkrWt
||
 |t| q?||v r~t|| ||}|d7 }|	| tjd|}| |}|t| q?|	d	|fS )
aY  Run source, save plots as images, and convert blocks to rst.

    Parameters
    ----------
    blocks : list of block tuples
        Code and text blocks from example. See `split_code_and_text_blocks`.
    src_path : str
        Path to example file.
    image_path : str
        Path where plots are saved (format string which accepts figure number).
    cfg : config object
        Sphinx config object created by Sphinx.

    Returns
    -------
    figure_list : list
        List of figure names saved by the example.
    rst_text : str
        Text with code wrapped code-block directives.
    r   rf   c                    s    g | ]\}} |d  v r|qS )ri   r   )r   r   r   
inline_tagr   r   r    6  s    

z"process_blocks.<locals>.<listcomp>allrS   r   r   r   )r"   rx   r9   r  plt
rcdefaultsrcParamsupdater5   closeexecr  codestr2rstsavefigr'   r   r   r   rv   
docstr2rst)r   r   r   rK   rz   r   idx_inline_plotr   image_fmt_strr   example_globalsr   fig_numr   blabelbrangebcontentfigure_namefigure_linkr   r  r   r     s4   




r   c                 C   s   d}d|  dd }|| S )z3Return reStructuredText code block from code stringz.. code-block:: python

	r   z
	)rv   )codestrcode_directiveindented_blockr   r   r   r%  S  s   r%  c                 C   s,   t |  t |  }| |d }t| | S )z&Return reStructuredText from docstringN)r   r   r   )docstridx_whitespace
whitespacer   r   r   r'  Z  s   r'  c                 C   s^   g }|   \}}tjj }dd |D D ]}t| t| | |	|| q|S )zSave all matplotlib figures.

    Parameters
    ----------
    image_path : str
        Path where plots are saved (format string which accepts figure number).
    c                 s   s    | ]}|j V  qd S r
   )num)r   mr   r   r   r   l  s    z#save_all_figures.<locals>.<genexpr>)
r"   
matplotlib_pylab_helpersGcfget_all_fig_managersr  figurer&  r'   r  )r   r   r   r)  fig_mngrr+  r   r   r   r   a  s   
r   )r   )1r0   r   r   r   r  r  rt   	itertoolsnumpyr   r:  usematplotlib.pyplotpyplotr  skimager   r   skimage.util.dtyper   notebook_docr   docutils.corer   sphinx.domains.pythonr   r   r   r   rq   r   ry   r   r	   r@   r=   rJ   rW   rp   rr   r   r   r   r   r   r   r%  r'  r   r   r   r   r   <module>   sR    C

(
C 8