
\c           @   s|  d  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 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 m Z d d l m Z m Z m Z m Z 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( m) Z) m* Z* m+ Z+ d d l, m- Z- m. Z. m/ Z/ m0 Z0 d d l1 m2 Z2 d d l1 m3 Z3 y d d l4 Z4 Wn e5 k
 rd Z4 n Xe7 rSd d l8 m9 Z9 m: Z: m; Z; m< Z< m= Z= m> Z> m? Z? m@ Z@ mA ZA d d lB mC ZC d d lD mE ZE d d l mF ZF d d l# mG ZG d d lH mI ZI n  e jJ eK  ZL d eM f d     YZN d S(   s   
    sphinx.builders
    ~~~~~~~~~~~~~~~

    Builder superclass for all builders.

    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
iN(   t   path(   t   nodes(   t   cPickle(   t   RemovedInSphinx20Warning(   t	   CONFIG_OKt   CONFIG_CHANGED_REASON(   t   ImageAdapter(   t   SphinxError(   t   read_doc(   t   __(   t   i18nt   import_objectt   loggingt   rstt   status_iterator(   t
   BuildPhase(   t   bold(   t   sphinx_domains(   t   find_catalog(   t   Matcher(   t   SEPt	   ensuredirt   relative_urit   relpath(   t   ParallelTaskst   SerialTaskst   make_chunkst   parallel_available(   t   roles(   t
   directives(	   t   Anyt   Callablet   Dictt   Iterablet   Listt   Sequencet   Sett   Tuplet   Union(   t   Sphinx(   t   Config(   t   BuildEnvironment(   t   CatalogInfo(   t   Tagst   Builderc           B   s  e  Z d  Z d Z d Z d Z d& Z d Z e	 Z
 e	 Z e Z g  Z e	 Z e	 Z d   Z d   Z d   Z d   Z e d    Z d   Z d	   Z d& d
  Z d& d  Z d   Z d   Z d   Z d   Z d   Z d   Z  d   Z! d   Z" d   Z# d   Z$ d& d d  Z% d   Z& d   Z' d   Z( d   Z) d   Z* d d  Z+ d   Z, d   Z- d    Z. d!   Z/ d"   Z0 d#   Z1 d$   Z2 d%   Z3 RS('   s6   
    Builds target formats from the reST sources.
    t    t   nonec         C   s  | j  |  _  | j |  _ | j |  _ | j |  _ t |  j  | |  _ d  |  _ | j |  _ | j	 |  _	 | j
 |  _
 | j |  _ |  j j |  j  |  j j |  j  |  j j d |  j  |  j j d |  j  i  |  _ d |  _ d |  _ t |  _ d  |  _ d  S(   Ns	   format_%ss
   builder_%sR-   (   t   srcdirt   confdirt   outdirt
   doctreedirR   t   appt   Nonet   envt   warnt   infot   configt   tagst   addt   formatt   namet   imagest   imagedirt   imgpatht   Falset   parallel_okt   finish_tasks(   t   selfR3   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   __init__Z   s(    						c         C   s&   | |  _  |  j  j |  j |  j  d S(   s   Store BuildEnvironment object.N(   R5   t   set_versioning_methodt   versioning_methodt   versioning_compare(   RC   R5   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   set_environmentx   s    	c         G   s   |  j  j j |   S(   s   Return a class of translator.(   R3   t   registryt   get_translator_class(   RC   t   args(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyRJ      s    c         G   s   |  j  j j |  |  S(   s   Return an instance of translator.

        This method returns an instance of ``default_translator_class`` by default.
        Users can replace the translator class with ``app.set_translator()`` API.
        (   R3   RI   t   create_translator(   RC   RK   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyRL      s    c         C   sQ   |  j  j j |   } | d k rJ |  j d k rJ t j d t d d d S|  j S(   sC   Return a class of translator.

        .. deprecated:: 1.6
        s   builder.translator_class() is now deprecated. Please use builder.create_translator() and builder.default_translator_class instead.t
   stackleveli   N(	   R3   RI   RJ   R4   t   default_translator_classt   warningsR6   R   RL   (   RC   t   translator_class(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyRP      s    	c         C   s   d S(   so   Load necessary templates and perform initialization.  The default
        implementation does nothing.
        N(    (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   init   s    c         C   sJ   |  j  j r* t |  j  j d    |  _ n d d l m } |   |  _ d S(   s&   Return the template bridge configured.s   template_bridge settingi(   t   BuiltinTemplateLoaderN(   R8   t   template_bridgeR   t	   templatest   sphinx.jinja2glueRR   (   RC   RR   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   create_template_bridge   s
    c         C   s
   t   d S(   s   Return the target URI for a document name.

        *typ* can be used to qualify the link characteristic for individual
        builders.
        N(   t   NotImplementedError(   RC   t   docnamet   typ(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   get_target_uri   s    c         C   s"   t  |  j |  |  j | |   S(   s   Return a relative URI between two source filenames.

        May raise environment.NoUri if there's no way to return a sensible URI.
        (   R   RZ   (   RC   t   from_t   toRY   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   get_relative_uri   s    c         C   s
   t   d S(   sD  Return an iterable of output files that are outdated, or a string
        describing what an update build will build.

        If the builder does not output individual files corresponding to
        source files, return a string here.  If it does, return an iterable
        of those files that need to be written.
        N(   RW   (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   get_outdated_docs   s    	c         C   s   g  S(   s;   Return list of paths for assets (ex. templates, CSS, etc.).(    (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   get_asset_paths   s    c         C   sJ  t  |  j  } x4| j t j  D] } d | d k r> q" n  d | d k rx |  j D]& } | d j | d	  } | rX PqX qX Wt | d  } | j	 | d  } | r t
 j t d  |  j | | d | q" t
 j t d  |  j | d | q" | | d <n
 | d } | |  j j k r'q" n  |  j j | d |  j | <q" Wd	 S(
   s+   Pick the best candidate for all image URIs.t   ?t
   candidatest   *t   uris2   a suitable image for %s builder not found: %s (%s)t   locations-   a suitable image for %s builder not found: %si   N(   R   R5   t   traverseR   t   imaget   supported_image_typest   getR4   t   sortedt   get_original_image_urit   loggert   warningR	   R<   R=   (   RC   t   doctreeR=   t   nodet   imgtypet	   candidatet	   mimetypest	   image_uri(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   post_process_images   s,    
c            s     j  j s d  S  f d   } t j t t d   |  xK t | t d  d t |    j j	 d | D] } | j
   j  j  qm Wd  S(   Nc            s%   t  |  j   j j  j t j t  S(   N(   R   t   mo_pathR5   R/   t   replaceR    t   sepR   (   t   cat(   RC   (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   cat2relpath   s    s   building [mo]: s   writing output... t	   darkgreent   stringify_func(   R8   t   gettext_auto_buildRk   R7   R   R	   R   t   lenR3   t	   verbosityt   write_mot   language(   RC   t   catalogst   messageRx   t   catalog(    (   RC   s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   compile_catalogs   s    c      
   C   s   t  j g  |  j j D] } t j |  j |  ^ q |  j j d |  j j d t	 d t
 d g  } t d  t |  } |  j | |  d  S(   Nt   charsett	   force_allt   excludeds   **/.?**s   all of %d po files(   R
   t   find_catalog_source_filesR8   t   locale_dirsR    t   joinR/   R   t   source_encodingt   TrueR   R	   R|   R   (   RC   t   xR   R   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   compile_all_catalogs  s    +c      
      s     f d   } t  t | |   } | j d   t j g    j j D] } t j	   j
 |  ^ qD   j j d t |  d   j j d t d g  } t d  t |  }   j | |  d  S(   Nc            s<     j  j t j |    } | r4 t |   j j  Sd  Sd  S(   N(   R5   t   path2docR    t   abspathR   R8   t   gettext_compactR4   (   t   fpathRX   (   RC   (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt	   to_domain  s    t   domainsR   R   s   **/.?**s*   targets for %d po files that are specified(   t   sett   mapt   discardR4   R
   R   R8   R   R    R   R/   R   t   listR   R   R	   R|   R   (   RC   t   specified_filesR   t   specified_domainsR   R   R   (    (   RC   s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   compile_specific_catalogs  s    +c         C   s   t  j g  |  j j D] } t j |  j |  ^ q |  j j d |  j j d t	 d g  } t
 d  t |  } |  j | |  d  S(   NR   R   s   **/.?**s,   targets for %d po files that are out of date(   R
   R   R8   R   R    R   R/   R   R   R   R	   R|   R   (   RC   R   R   R   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   compile_update_catalogs"  s    +c         C   s#   |  j  d d t d  d d d S(   s   Build all source files.t   summarys   all source filest   methodt   allN(   t   buildR4   R	   (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt	   build_all.  s    c            s]  t  |  j  d } g  } d	 } t |  j j  } x | D]   t j t j         j	 |  j  s t
 j t d     q8 n  t j    p t   f d   | D  s t
 j t d     q8 n    |   x2 | D]* }   j |  r   t  |     Pq q W  j t j t    | j    q8 W|  j | d d d t d  t  |  d	 S(
   s>   Only rebuild as much as needed for changes in the *filenames*.i   sI   file %r given on command line is not under the source directory, ignoringc         3   s"   |  ] } t  j   |  Vq d  S(   N(   R    t   isfile(   t   .0t   suffix(   t   filename(    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pys	   <genexpr>C  s    s6   file %r given on command line does not exist, ignoringR   t   specificR   s%   %d source files given on command lineN(   R|   R/   R4   t   tupleR8   t   source_suffixR    t   normpathR   t
   startswithRk   Rl   R	   R   t   anyt   endswithRu   Rv   R   t   appendR   (   RC   t	   filenamest   dirlent   to_writet   suffixesR   (    (   R   s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   build_specific3  s0    
c         C   sd   |  j    } t | t  r1 |  j d g |  n/ t |  } |  j | d t d  t |  d S(   s8   Only rebuild what was changed or added since last build.t   __all__R   s0   targets for %d source files that are out of dateN(   R^   t
   isinstancet   strR   R   R	   R|   (   RC   t   to_build(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   build_updateQ  s    	t   updatec   
   	   C   s  | r1 t  j t t d  |  j  d |  n  t j    t |  j    } Wd QXt	 |  } t  j t t d   d d x- |  j
 j |  j |  D] } | j |  q Wt	 |  | } | r t  j t d  |  n t  j t d   | rd	 d
 l m } t  j t t d   d t t t j |  j |  d    }	 t j |  j
 |	 t j  Wd QXt  j t d   t j |  j _ t  j t t d   d t |  j
 j   t  j t d   n0 | d k r| rt  j t t d    d St j |  j _ | r9| d g k r9t |  |  j
 j @} n  t rr|  j j d k rr|  j  rr|  j j! d  |  _" n	 t# |  _" t$   |  _% |  j& | t' |  |  |  j(   |  j% j   d S(   sa   Main build method.

        First updates the environment, and then calls :meth:`write`.
        s   building [%s]s   : Ns"   looking for now-outdated files... t   nonli   s   %d founds
   none foundi(   t   ENV_PICKLE_FILENAMEs   pickling environment... t   wbt   dones   checking consistency... R   s   no targets are out of date.R   t   write()   Rk   R7   R   R	   R<   R   t   pending_warningsR   t   readR|   R5   t   check_dependentsR3   R:   t   sphinx.applicationR   R   t   openR    R   R2   t   picklet   dumpt   HIGHEST_PROTOCOLR   t   CONSISTENCY_CHECKt   phaset   check_consistencyt	   RESOLVINGt
   found_docsR   t   parallelt   allow_parallelt   is_parallel_allowedRA   R@   R   RB   R   R   t   finish(
   RC   t   docnamesR   R   t   updated_docnamest   doccountRX   t   outdatedR   t   f(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR   ]  sF    +!!	
c         C   s  t  j t d  d t |  j j |  j |   |  j j t k } |  j j	 |  \ } } } xC |  j
 j d |  | | |  D]# } | j t |  |  j j @ q{ W| s | r | j |  j j |  j j @ n  | rt j |  j j d  } t  j d | d t n  t  j d t |  t |  t |   x7 | D]/ } |  j
 j d |  j |  |  j j |  q4Wt | | B } |  j
 j d |  j |  t rt |  d	 k r|  j
 j d
 k r|  j
 j d  }	 n t }	 |	 r|  j | d |  j
 j n |  j |  |  j j |  j j k rAt d |  j j |  j j    n  x< |  j
 j d |  j  D]" }
 |
 d k	 rZ| j  |
  qZqZWt |  j _ t |  S(   s   (Re-)read all files new or changed since last update.

        Store all environment docnames in the canonical format (ie using SEP as
        a separator in place of os.path.sep).
        s   updating environment: R   s   env-get-outdatedR-   s   [%s] s    %s added, %s changed, %s removeds   env-purge-docs   env-before-read-docsi   i   R   t   nprocs   master file %s not founds   env-updatedN(!   Rk   R7   R   R   R5   t
   find_filesR8   t   config_statusR   t   get_outdated_filesR3   t   emitR   R   R   t   glob_toctreesR   Rh   R|   t	   clear_docRi   R   R   R   R@   t   _read_parallelt   _read_serialt
   master_doct   all_docsR   t   doc2pathR4   t   extend(   RC   t   updatedt   addedt   changedt   removedt   docst   reasonRX   R   t   par_okt   retval(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR     s@    %! 	*c         C   si   xb t  | d d t |  |  j j  D]< } |  j j d |  j |  |  j j |  |  j |  q% Wd  S(   Ns   reading sources... t   purples   env-purge-doc(   R   R|   R3   R}   R   R5   R   R   (   RC   R   RX   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR     s
    c   	         s   x7 | D]/ }   j  j d   j |    j j |  q W  f d   }   f d   } t |  } t | |  } x? t | d d t |    j  j  D] } | j	 | | |  q Wt
 j t d   | j   d  S(   Ns   env-purge-docc            sC     j    j _  x |  D] }   j |  q Wt j   j t j  S(   N(   R3   R5   R   R   t   dumpsR   (   R   RX   (   RC   (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   read_process  s    c            s,   t  j |  }   j j |  |   j  d  S(   N(   R   t   loadsR5   t   merge_info_fromR3   (   R   t   otherenvR5   (   RC   (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   merge  s    s   reading sources... R   s   waiting for workers...(   R3   R   R5   R   R   R   R   R|   R}   t   add_taskRk   R7   R   R   (	   RC   R   R   RX   R   R   t   taskst   chunkst   chunk(    (   RC   s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR     s    c         C   s  |  j  j |  t j |  j d  } t j |  rG |  j  j |  n  t |  j   H t j	 | |  j
 j	  ) t |  j |  j  |  j  j |   } Wd QXWd QXt t j   t j |  j  j |    |  j  j | <|  j  j j   |  j  j j   |  j | |  d S(   s>   Parse a file and add/update inventory entries for the doctree.s   docutils.confN(   R5   t   prepare_settingsR    R   R0   R   t   note_dependencyR   R   t   default_roleR8   R   R3   R   t   maxt   timet   getmtimeR   t	   temp_datat   cleart   ref_contextt   write_doctree(   RC   RX   t   docutilsconfRm   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR     s     0(c         C   s   d | _ d | _ d | j _ d | j _ d | j _ |  j j | |  j j d  } t	 t
 j |   t | d   } t j | | t j  Wd QXd S(   s   Write the doctree to a file.s   .doctreeR   N(   R4   t   reportert   transformert   settingst   warning_streamR5   t   record_dependenciesR   R2   R   R    t   dirnameR   R   R   R   (   RC   RX   Rm   t   doctree_filenameR   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR   %  s    		c         C   sw  | d  k s | d g k r* |  j j } n  | d k rO t |  t |  B} n t |  } t j t d  d j t |    x\ t	 |  D]N } xE |  j j
 j | t    D]( } | |  j j k r | j |  q q Wq W| j |  j j  t j t t d   d t |  j |  t j t d   |  j r`|  j t |  d |  j j d	 n |  j t |   d  S(
   NR   R   s   docnames to write: %ss   , s   preparing documents... R   R   R   i   (   R4   R5   R   R   Rk   t   debugR	   R   Ri   R   t   files_to_rebuildRh   R:   R8   R   R7   R   R   t   prepare_writingRA   t   _write_parallelR3   R   t   _write_serial(   RC   t   build_docnamesR   R   R   RX   t
   tocdocname(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR   4  s$    %"	c      
   C   s   t  j    x t | t d  d t |  |  j j  D]Y } t j |  j _	 |  j
 j | |   } t j |  j _	 |  j | |  |  j | |  q8 WWd  QXd  S(   Ns   writing output... Ry   (   R   R   R   R	   R|   R3   R}   R   R   R   R5   t   get_and_resolve_doctreet   WRITINGt   write_doc_serializedt	   write_doc(   RC   R   RX   Rm   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR	  S  s    c            sh    f d   } | d | d } } t  j   j _   j j |    } t  j   j _   j | |    j | |  t	 |  } t
 | |  } t  j   j _ x t | t d  d t |    j j  D]q } g  }	 xR t |  D]D \ }
 }   j j |    }   j | |  |	 j | | f  q W| j | |	  q Wt j t t d    | j   d  S(   Nc            s:   t  j   j _ x$ |  D] \ } }   j | |  q Wd  S(   N(   R   R  R3   R   R  (   R   RX   Rm   (   RC   (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   write_process`  s    i    i   s   writing output... Ry   s   waiting for workers...(   R   R   R3   R   R5   R  R  R  R  R   R   R   R	   R|   R}   t	   enumerateR   R   Rk   R7   R   R   (   RC   R   R   R  t	   firstnameRm   R   R   R   t   argt   iRX   (    (   RC   s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR  ^  s(    c         C   s
   t   d S(   s?   A place where you can add logic before :meth:`write_doc` is runN(   RW   (   RC   R   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR    s    c         C   s
   t   d S(   s5   Where you actually write something to the filesystem.N(   RW   (   RC   RX   Rm   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR    s    c         C   s   d S(   so   Handle parts of write_doc that must be called in the main process
        if parallel build is active.
        N(    (   RC   RX   Rm   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR    s    c         C   s   d S(   sW   Finish the building process.

        The default implementation does nothing.
        N(    (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR     s    c         C   s   d S(   sQ   Cleanup any resources.

        The default implementation does nothing.
        N(    (   RC   (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   cleanup  s    c         C   s\   y' d |  j  | f } t |  j |  SWn. t k
 rW d | | f } t |  j |  SXd S(   s   Return a builder specific option.

        This method allows customization of common builder settings by
        inserting the name of the current builder in the option key.
        If the key does not exist, use default as builder name.
        s   %s_%sN(   R<   t   getattrR8   t   AttributeError(   RC   t   optiont   defaultt   optname(    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   get_builder_config  s    
N(4   t   __name__t
   __module__t   __doc__R<   R;   t   epilogR4   RN   RF   R@   RG   R   R   t   use_message_catalogRg   t   supported_remote_imagest   supported_data_uri_imagesRD   RH   RJ   RL   t   propertyRP   RQ   RV   RZ   R]   R^   R_   Rs   R   R   R   R   R   R   R   R   R   R   R   R   R   R   R	  R  R  R  R  R   R  R  (    (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyR,   9   s\   							
					"							G	?							!					(O   R  R   RO   t   osR    t   docutilsR   t	   six.movesR   R   t   sphinx.deprecationR   t   sphinx.environmentR   R   t!   sphinx.environment.adapters.assetR   t   sphinx.errorsR   t	   sphinx.ioR   t   sphinx.localeR	   t   sphinx.utilR
   R   R   R   R   t   sphinx.util.build_phaseR   t   sphinx.util.consoleR   t   sphinx.util.docutilsR   t   sphinx.util.i18nR   t   sphinx.util.matchingR   t   sphinx.util.osutilR   R   R   R   t   sphinx.util.parallelR   R   R   R   t   sphinxR   R   t   multiprocessingt   ImportErrorR4   R@   t   typingR   R   R    R!   R"   R#   R$   R%   R&   R   R'   t   sphinx.configR(   R)   R*   t   sphinx.util.tagsR+   t	   getLoggerR  Rk   t   objectR,   (    (    (    s7   lib/python2.7/site-packages/sphinx/builders/__init__.pyt   <module>
   sD   (""
@