
\c           @   s[  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 m Z d d l	 m
 Z
 d d l m Z d d l m Z m Z d d l m Z d d l m Z d d	 l m Z d d l 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 m Z d d l  m! Z! d d l" m# Z# d d l$ m% Z% m& Z& d d l' m( Z( m) Z) m* Z* d d l+ m, Z, m- Z- m. Z. m/ Z/ d d l0 m1 Z1 e2 r!d d l3 m4 Z4 m5 Z5 m6 Z6 m7 Z7 m8 Z8 m9 Z9 d d l: m; Z; d d l< m= Z= d d l> m? Z? d d l m@ Z@ n  e* jA eB  ZC e jD d  ZE e jD d  ZF d e
 jG f d     YZH d   ZI d   ZJ d    ZK d! e
 jG f d"     YZL d#   ZM d ZO d$ e f d%     YZP d&   ZQ d' e- f d(     YZR d)   ZS d* d+  ZT d,   ZU d* d- d.  ZV d/   ZW d g d0  ZX d1   ZY i  g  d2  ZZ d3   Z[ d4   Z\ d5   Z] d S(6   s  
    sphinx.ext.autosummary
    ~~~~~~~~~~~~~~~~~~~~~~

    Sphinx extension that adds an autosummary:: directive, which can be
    used to generate function/method/attribute/etc. summary lists, similar
    to those output eg. by Epydoc and other API doc generation tools.

    An :autolink: role is also provided.

    autosummary directive
    ---------------------

    The autosummary directive has the form::

        .. autosummary::
           :nosignatures:
           :toctree: generated/

           module.function_1
           module.function_2
           ...

    and it generates an output table (containing signatures, optionally)

        ========================  =============================================
        module.function_1(args)   Summary line from the docstring of function_1
        module.function_2(args)   Summary line from the docstring
        ...
        ========================  =============================================

    If the :toctree: option is specified, files matching the function names
    are inserted to the toctree with the given prefix:

        generated/module.function_1
        generated/module.function_2
        ...

    Note: The file names contain the module:: or currentmodule:: prefixes.

    .. seealso:: autosummary_generate.py


    autolink role
    -------------

    The autolink role functions as ``:obj:`` when the name referred can be
    resolved to a Python object, and otherwise it becomes simple emphasis.
    This can be used as the default role to make links 'smart'.

    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
iN(   t
   ModuleType(   t   nodes(   t
   directives(   t   RSTStateMachinet   state_classes(   t   ViewList(   t   string_types(   t	   text_type(   t   addnodes(   t   RemovedInSphinx20Warning(   t   TocTree(   t   get_documenters(   t   DocumenterBridget   Options(   t   import_module(   t   __(   t   ModuleAnalyzert   PycodeError(   t   import_objectt   rstt   logging(   t   NullReportert   SphinxDirectivet   new_documentt   switch_source_input(   t   Matcher(   t   Anyt   Dictt   Listt   Tuplet   Typet   Union(   t   Inliner(   t   Sphinx(   t   BuildEnvironment(   t
   Documenters	   \.(?:\s+)s   ::\s*$t   autosummary_tocc           B   s   e  Z RS(    (   t   __name__t
   __module__(    (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR$   g   s   c            s8   |  j  j  i   d     f d      |  d S(   si   Insert items described in autosummary:: to the TOC tree, but do
    not generate the toctree:: list.
    i   c            s   t   |  <x t |   D] \ } } yL t | t  rn t | d t j  rn t   j  j | d  w n  Wn t	 k
 r q n Xt | t
 j  s q n  |  k r   | | d  q q Wd  S(   Ni    i   (   t   Truet	   enumeratet
   isinstanceR$   R   t   toctreeR
   t   notet   docnamet
   IndexErrorR   t   section(   t   nodet   deptht   jt   subnode(   t	   crawl_toct   crawledt   env(    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR3   s   s    

N(   t   builderR5   (   t   appt   doctree(    (   R3   R4   R5   s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   process_autosummary_tock   s    c         C   s   t  j  d S(   s-   Hide autosummary toctree list in HTML output.N(   R   t   SkipNode(   t   selfR/   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   autosummary_toc_visit_html   s    c         C   s   d  S(   N(    (   R;   R/   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   autosummary_noop   s    t   autosummary_tablec           B   s   e  Z RS(    (   R%   R&   (    (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR>      s   c   	      C   s   y | d d d } x | D] } | d } | d } xl t  t |   D]X \ } } t | t j  rI t | j    } | j d d  } t j |  | | <qI qI Wq WWn t k
 r n Xd S(   s0   Make the first column of the table non-breaking.i    iu    u    N(	   R(   t   listR)   R   t   TextR   t   astextt   replaceR-   (	   R;   R/   t   tbodyt   rowt
   col1_entryt   parR1   R2   t   new_text(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   autosummary_table_visit_html   s    

"t   FakeDirectivec           B   s   e  Z d    Z RS(   c         C   s&   t  t |   j i  d  t   d  d  S(   Ni    (   t   superRI   t   __init__t   NoneR   (   R;   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyRK      s    (   R%   R&   RK   (    (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyRI      s   c    
      G   s;  d d l  m } m } t |   d k r: |  \ } } } n( t } |  \ } } t j d t d d t j	 |  ru | S| d k	 r t | | d  } n | } t | d  r | t   | j  } n | t   d  } g  t |  j   D]$ } | j | d t |  r | ^ q }	 |	 r3|	 j d	 d
    |	 d S| Sd S(   s   Get an autodoc.Documenter class suitable for documenting the given
    object.

    *obj* is the Python object to be documented, and *parent* is an
    another Python object (e.g. a module or a class) to which *obj*
    belongs to.
    i(   t   DataDocumentert   ModuleDocumenteri   se   the interface of get_documenter() has been changed. Please give application object as first argument.t
   stackleveli   R%   t    t   keyc         S   s   |  j  S(   N(   t   priority(   t   cls(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   <lambda>   s    N(   t   sphinx.ext.autodocRM   RN   t   lent   _appt   warningst   warnR	   t   inspectt   ismoduleRL   t   get_documentert   hasattrRI   R%   R   t   valuest   can_document_membert   Falset   sort(
   t   argsRM   RN   R7   t   objt   parentt   parent_doc_clst
   parent_docRS   t   classes(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR\      s*    		$t   Autosummaryc           B   sn   e  Z d  Z d Z d Z e Z e Z i e	 j
 d 6e	 j d 6e	 j
 d 6Z d   Z d   Z d   Z d   Z RS(	   s   
    Pretty table containing short signatures and summaries of functions etc.

    autosummary can also optionally generate a hidden toctree:: node.
    i    R*   t   nosignaturest   templatec         C   s/   |  j  j |  j j j j | d |  j  d  S(   Nt   line(   RX   t   appendt   statet   documentt   reportert   warningt   lineno(   R;   t   msg(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyRY      s    c         C   s  t    |  _ g  |  _ t   |  _ g  |  j D]D } | j   r+ t j d | j   d  r+ | j   j	   d ^ q+ } |  j
 |  } |  j |  } d |  j k rt j |  j j  } |  j d j   } g  } t |  j j  } x | D] \ }	 }
 } } t j | |  } t j t j | |   } | |  j j k r}| |  j j | d    ri|  j d |  q}|  j d |  n  | j |  q Wt j   } | | d <g  | D] } d  | f ^ q| d <d | d	 <d  | d
 <t d d |  } | j |  n  |  j | S(   Ns   ^[~a-zA-Z_]i    R*   s'   toctree references excluded document %rs&   toctree references unknown document %rt   includefilest   entriesit   maxdeptht   globRP   (   R   t   genoptRX   R   t   resultt   contentt   stript   ret   searcht   splitt	   get_itemst	   get_tablet   optionst	   posixpatht   dirnameR5   R,   R   t   configt   exclude_patternst   joint   normpatht
   found_docst   doc2pathRL   RY   Rl   R   R*   R$   (   R;   t   xt   namest   itemsR   R   t   tree_prefixt   docnamest   excludedt   namet   sigt   summaryt	   real_nameR,   t   tocnodet   docn(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   run   s<    	D		
#

c         C   s  t  |  j  } g  } d } x~| D]v} | } | j d  r] | d } | j d  d } n  y" t | d | \ } } }	 }
 Wn> t k
 r |  j d |  | j | d d | f  q" n Xt   |  _	 | } t
 | t  s |
 d	 | t |
  d } n  t |  j j | |	  |  |  } | j   s]|  j d
 |  | j | d d | f  q" n  | j   s|  j d |  | j | d d | f  q" n  | j j r| j   rq" n  y) t j | j    | _ | j j   Wn, t k
 r} t j d |  d | _ n X| j   } | s+d } n+ t d | t |   } t | d | } | j  d  t! |  j	 j" |  j# j$  } | j | | | | f  q" W| S(   s}   Try to import the given names, and return a list of
        ``[(name, signature, summary_string, real_name), ...]``.
        i2   t   ~i   t   .it   prefixess   failed to import %sRP   s   ::s   failed to parse name %ss   failed to import object %ss$   [autodoc] module analyzer failed: %si
   t	   max_charsN(%   t   get_import_prefixes_from_envR5   t
   startswithR}   t   import_by_namet   ImportErrorRY   Rl   R   Rx   R)   R    RV   R\   R7   t
   parse_nameR   R   t   memberst   check_moduleR   t
   for_modulet   get_real_modnamet   analyzert   find_attr_docsR   t   loggert   debugRL   t   format_signaturet   maxt   mangle_signaturet   add_contentt   extract_summaryt   dataRm   Rn   (   R;   R   R   R   t   max_item_charsR   t   display_nameR   Rc   Rd   t   modnamet	   full_namet
   documentert   errR   R   R   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR~   !  sZ    
"!	c            sS  t  j   } d | d <t d  } t j d d d g } | j |  t j d d d } | j |  | j t j d d d	  | j t j d d d
  t j d    | j       f d   } xw | D]o \ } } }	 }
 d } d  j	 k rd | | |
 t
 j |  f } n d | | |
 f } |	 } | | |  q W| | g S(   s   Generate a proper list of table nodes for autosummary:: directive.

        *items* is a list produced by :meth:`get_items`.
        s   \X{1}{2}\X{1}{2}t   specRP   Rg   t	   longtablet   colsi   t   colwidthi
   iZ   c       
      s   t  j d  }  j j   \ } } x |  D] } t  j d  } t   } | j | d | | f  t  j |  o  j j	 | d |  y' t
 | d t  j  r | d } n  Wn t k
 r n X| j t  j d |   Wd  QXq+ W  j |  d  S(   NRP   s   %s:%d:<autosummary>i    (   R   RD   t   state_machinet   get_source_and_linet	   paragraphR   Rl   R   Rm   t   nested_parseR)   R-   t   entry(   t   column_textsRD   t   sourceRk   t   textR/   t   vl(   t   bodyR;   (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt
   append_row~  s    	#Rc   Ri   s   :%s:`%s <%s>`\ %ss   :%s:`%s <%s>`(   R   t   tabular_col_specR>   R   t   tableRl   t   tgroupt   colspecRC   R   R   t   escape(   R;   R   t
   table_specR   t
   real_tablet   groupR   R   R   R   R   t	   qualifiert   col1t   col2(    (   R   R;   s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR   k  s(    
"(   R%   R&   t   __doc__t   required_argumentst   optional_argumentsR`   t   final_argument_whitespaceR'   t   has_contentR   t	   unchangedt   flagt   option_specRY   R   R~   R   (    (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyRh      s   

		(	Jc         C   s   |  j  d  d j   S(   s+   Strip a type hint from argument definition.t   :i    (   R}   Rz   (   t   s(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   strip_arg_typehint  s    i   c   
   	   C   s  t  j d d |   } t  j d d |  j   } t  j d d |  } t  j d d |  } t  j d d |  } g  } g  } t  j d	  } x^ | r | j |  } | s | j d
  } Pn  | j d | j d   | j d  d  } q Wx* t |  D] \ } } t	 |  | | <q Wx* t |  D] \ } }	 t	 |	  | | <q%Wt
 d
 | d | d }  | r|  sd t
 d
 | d | d }  qt |   | d d d k  r|  d t
 d
 | d | t |   d d 7}  qn  d |  S(   s5   Reformat a function signature to a more compact form.s   \)\s*->\s.*$t   )s
   ^\((.*)\)$s   \1s   \\\\RP   s   \\'s   '[^']*'s   ^(.*, |)([a-zA-Z0-9_*]+)=s   , i    i   i   iR   s   [%s]i   i   s   [, %s]u   (%s)(   R{   t   subRz   t   compileR|   R}   t   insertR   R(   R   t   limited_joinRV   (
   R   R   R   Rb   t   optst   opt_ret   mt   it   argt   opt(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR     s6    	 #c         C   s  x( |  r* |  d j    r* |  j d  q Wx4 t |   D]& \ } } | j    s8 |  |  }  Pq8 q8 W|  g  k rr d St t d  } t d | j  } t   | _ | j	 |  |  t
 | d t j  s |  d j    } n t j d j |    } t |  d k r| d j    } nZ d } xQ | rn| | j d  d 7} g  | (| j	 | g |  | j t j  sPqqWt j d |  } | S(   s   Extract summary from docstring.i    RP   t   Bodyt    i   R   (   Rz   t   popR(   R   R   R   t   settingsR   Ro   R   R)   R   R   t
   periods_reR}   R   RV   t   traverset   system_messaget
   literal_reR   (   t   docRn   R   t   pieceR   R/   R   t	   sentences(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR     s4    
	s   ...c   	      C   s   |  j  |  } t |  | k  r% | Sd } d } xX t |  D]J \ } } | t |  t |   7} | | t |  k  r | d 7} q> Pq> W|  j  t | |   | g  S(   s   Join a number of strings to one, limiting the length to *max_chars*.

    If the string overflows this limit, replace the last fitting item by
    *overflow_marker*.

    Returns: joined_string
    i    i   (   R   RV   R(   R?   (	   t   sepR   R   t   overflow_markert   full_strt   n_charst   n_itemsR1   t   item(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR     s    	c         C   s   d g } |  j j d  } | r4 | j d |  n  |  j j d  } | r | rm | j d | d |  q | j d |  n  | S(   s`   
    Obtain current Python import prefixes (for `import_by_name`)
    from ``document.env``
    s	   py:modulei    s   py:classR   N(   RL   t   ref_contextt   getR   (   R5   R   t
   currmodulet	   currclass(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR     s    	c         C   s   g  } x| | D]t } yM | r4 d j  | |  g  } n |  } t |  \ } } } | | | | f SWq t k
 r | j |  q Xq Wt d d j  |    d S(   s~   Import a Python object that has the given *name*, under one of the
    *prefixes*.  The first name that succeeds is used.
    R   s   no module named %ss    or N(   R   t   _import_by_nameR   Rl   (   R   R   t   triedt   prefixt   prefixed_nameRc   Rd   R   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR   4  s    c   
      C   s  ym|  j  d  } d j | d   } | ru y* t |  } t | | d  | | f SWqu t t t f k
 rq qu Xn  d } d } xx t t	 d t
 |  d   D]W } | } d j | |   } y t |  Wn t k
 r q n X| t j k r Pq q W| t
 |  k  rXd } t j | } x' | | D] } | } t | |  } q,W| | | f St j | d | f SWn. t t t t f k
 r}	 t |	 j    n Xd S(   s+   Import a Python object given its full name.R   ii    i   N(   R}   R   R   t   getattrR   R-   t   AttributeErrorRL   t   reversedt   rangeRV   t   syst   modulest
   ValueErrort   KeyErrorRb   (
   R   t
   name_partsR   t   modt   last_jR1   Rd   Rc   t   obj_namet   e(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyR   G  s<    &c         C   s   | j  j j } d } | j d  j d  d | | | | | |  } | d d }	 t |  }
 y# t |	 d |
  \ } } } } WnI t k
 r |	 d } t	 j
 | | d j   d | d | d d <n X| S(   s   Smart linking role.

    Expands to ':obj:`text`' if `text` is an object that can be imported;
    otherwise expands to '*text*'.
    t   pyRc   i    t	   reftargetRg   N(   Rn   R   R5   RL   t
   get_domaint   roleR   R   R   R   t   emphasisRA   (   t   typt   rawtextt   etextRq   t   inlinerR   Ry   R5   t   rt   pnodeR   R   Rc   Rd   R   t   content_node(    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   autolink_roles  s    #
c            sF     f d   } d  } x*   j j D] } d | |  k r" | Sq" Wd  S(   Nc            sP     j  j   j |   } | d  k r( d St | t  rI t | d  } n  | j S(   Nt   restructuredtexts   source parser(   R  (   t   registryt   get_source_parsersR   RL   R)   R   R   t	   supported(   t   suffixt   parser_class(   R7   (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   get_supported_format  s    R  (   RL   R   t   source_suffix(   R7   R  R  (    (   R7   s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   get_rst_suffix  s    	c         C   sM  |  j  j } | rw t | d  rw |  j j } g  | j D]6 } t j j | j	 |   r8 | j	 | d d  ^ q8 } n  | s d  Sd d l m } t |  j  j  } g  | D]0 } | | j t |   r | d p d ^ q } t |   } | d  k rt j t d   d  S| | d |  j d	 t j d
 t j d | d |  j d |  d  S(   Nt   __len__t   basei(   t   generate_autosummary_docsi    RP   sb   autosummary generats .rst files internally. But your source_suffix does not contain .rst. Skipped.R6   RY   t   infoR  t	   base_pathR7   (   R   t   autosummary_generateR]   R6   R5   R   t   ost   patht   isfileR   RL   t   sphinx.ext.autosummary.generateR!  R?   R  t   endswitht   tupleR  R   Rp   R   R"  t   srcdir(   R7   t   genfilesR5   R   R!  t   extt   genfileR  (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   process_generate_options  s&    9:c         C   s  |  j  d  |  j t d t t f d t t f d t t f d t t f d t t f |  j t d t t f d t t f d t t f d t t f d t t f |  j d t  |  j	 d t
  |  j d	 t  |  j d
 t  |  j d g  t t g  i t j d 6t d 6S(   Ns   sphinx.ext.autodoct   htmlt   latexR   t   mant   texinfot   autosummaryt   autolinks   doctree-reads   builder-initedR$  t   versiont   parallel_read_safe(   t   setup_extensiont   add_nodeR$   R<   R=   R>   RH   t   add_directiveRh   t   add_roleR  t   connectR9   R/  t   add_config_valueR'   t   boolt   sphinxt   __display_version__(   R7   (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   setup  s&    (^   R   RZ   R%  R   R{   R   RX   t   typesR    t   docutilsR   t   docutils.parsers.rstR   t   docutils.parsers.rst.statesR   R   t   docutils.statemachineR   t   sixR   R   R?  R   t   sphinx.deprecationR	   t#   sphinx.environment.adapters.toctreeR
   RU   R   t   sphinx.ext.autodoc.directiveR   R   t   sphinx.ext.autodoc.importerR   t   sphinx.localeR   t   sphinx.pycodeR   R   t   sphinx.utilR   R   R   t   sphinx.util.docutilsR   R   R   R   t   sphinx.util.matchingR   R`   t   typingR   R   R   R   R   R   t   docutils.utilsR    t   sphinx.applicationR!   t   sphinx.environmentR"   R#   t	   getLoggerR%   R   R   R   R   t   commentR$   R9   R<   R=   R>   RH   RL   RW   RI   R\   Rh   R   R   R   R   R   R   R   R  R  R/  RA  (    (    (    s>   lib/python2.7/site-packages/sphinx/ext/autosummary/__init__.pyt   <module>6   sn   ".					0	0	1		,		