U
    \Shh                     @  s  d Z ddlmZ ddlZddlZddlZddlmZ ddl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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,m-Z- ddl.m/Z/ ddl0m1Z1m2Z2m3Z3 ddl4m5Z5m6Z6m7Z7m8Z8 ddl9m:Z:m;Z;m<Z<m=Z= ddl>m?Z? ddl@mAZA ddlBmCZC ddlBmDZD e	rddlEmFZF e%GeHZIG dd dZJdS )z$Builder superclass for all builders.    )annotationsN)path)TYPE_CHECKINGAnyIterableSequence)nodes)Node)DependencyList)Config)CONFIG_CHANGED_REASON	CONFIG_OKBuildEnvironment)ImageAdapter)SphinxError)EventManager)__)UnicodeDecodeErrorHandlerget_filetypeimport_objectloggingrst)
BuildPhase)bold)progress_messagestatus_iterator)sphinx_domains)CatalogInfoCatalogRepositorydocname_to_domain)SEP	ensuredirrelative_urirelpath)ParallelTasksSerialTasksmake_chunksparallel_available)Tags)NoneType)
directives)roles)Sphinxc                   @  sx  e Zd ZU dZdZdZdZded< dZdZ	dZ
dZg Zded	< dZdZd
dddddZdddddZdddddZddddZddddZdpddddd d!Zdqddddd"d#d$Zd%dd&d'Zddd(d)Zd*dd+d,d-Zd.ddd/d0d1Zddd2d3Zddd4d5d6Zddd7d8Zddd9d:Zddd;d<d=Zddd>d?ZdrdAddddBdCdDZ dddEdFZ!dddGdHdIZ"ddJddKdLdMZ#ddNddOddPdQdRZ$ddNddSdOddTdUdVZ%dsdAdWdddXdYdZZ&dWddGd[d\Z'dWdJddKd]d^Z(d_ddGd`daZ)dddbdcZ*ddSddddedfZ+ddSddddgdhZ,dddidjZ-dddkdlZ.ddddmdndoZ/dS )tBuilderz6
    Builds target formats from the reST sources.
     ztype[nodes.NodeVisitor]Zdefault_translator_classnoneFT	list[str]supported_image_typesr,   r   None)appenvreturnc                 C  s   |j | _ |j| _|j| _|j| _t| j || _|| _| j| j| j	 |j
| _
|j| _|j| _| j| j | j| j | jd| j  | jd| j  i | _d| _d| _d| _d | _d S )Nz	format_%sz
builder_%sr.   F)srcdirconfdirZoutdir
doctreedirr!   r3   r4   Zset_versioning_methodversioning_methodversioning_compareeventsconfigtagsaddformatnameimagesZimagedirZimgpathparallel_okfinish_tasks)selfr3   r4    rE   K/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/builders/__init__.py__init__L   s,    

zBuilder.__init__r   )argsr5   c                 G  s   | j j| S )zReturn a class of translator.)r3   registryget_translator_classrD   rH   rE   rE   rF   rJ   j   s    zBuilder.get_translator_classznodes.NodeVisitorc                 G  s   | j jj| f| S )zReturn 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   create_translatorrK   rE   rE   rF   rL   n   s    zBuilder.create_translator)r5   c                 C  s   dS )zoLoad necessary templates and perform initialization.  The default
        implementation does nothing.
        NrE   rD   rE   rE   rF   initw   s    zBuilder.initc                 C  s4   | j jrt| j jd | _nddlm} | | _dS )z&Return the template bridge configured.ztemplate_bridge settingr   )BuiltinTemplateLoaderN)r<   Ztemplate_bridger   Z	templatesZsphinx.jinja2gluerO   )rD   rO   rE   rE   rF   create_template_bridge}   s    
zBuilder.create_template_bridgeNstr
str | None)docnametypr5   c                 C  s   t dS )zReturn the target URI for a document name.

        *typ* can be used to qualify the link characteristic for individual
        builders.
        NNotImplementedError)rD   rS   rT   rE   rE   rF   get_target_uri   s    zBuilder.get_target_uri)from_torT   r5   c                 C  s   t | || ||S )zReturn a relative URI between two source filenames.

        May raise environment.NoUri if there's no way to return a sensible URI.
        )r"   rW   )rD   rX   rY   rT   rE   rE   rF   get_relative_uri   s    

zBuilder.get_relative_urizstr | Iterable[str]c                 C  s   t dS )aD  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.
        NrU   rM   rE   rE   rF   get_outdated_docs   s    zBuilder.get_outdated_docsc                 C  s   g S )z;Return list of paths for assets (ex. templates, CSS, etc.).rE   rM   rE   rE   rF   get_asset_paths   s    zBuilder.get_asset_pathsr	   )doctreer5   c                 C  s   t | j}|tjD ]}d|d kr(qd|d kr| jD ]}|d |d}|r: qq:t|d }||d }|rt	j
td| j|||d qt	j
td| j||d q||d< n|d }|| jjkrq| jj| d	 | j|< qdS )
z+Pick the best candidate for all image URIs.?
candidates*Nuriz2a suitable image for %s builder not found: %s (%s))locationz-a suitable image for %s builder not found: %s   )r   r4   findallr   imager1   getsortedZget_original_image_uriloggerwarningr   r@   rA   )rD   r]   rA   nodeZimgtype	candidate	mimetypesZ	image_urirE   rE   rF   post_process_images   s:    


   
  
zBuilder.post_process_imageszset[CatalogInfo])catalogsmessager5   c                   st    j jsd S ddd fdd}tttd|  t|tddt| jj	|d	D ]}|
 j j j j qVd S )
Nr   rQ   )catr5   c                   s   t | j jjtjtS N)r#   Zmo_pathr4   r6   replacer   sepr    )rp   rM   rE   rF   cat2relpath   s    z-Builder.compile_catalogs.<locals>.cat2relpathzbuilding [mo]: writing output... 	darkgreen)Zstringify_func)r<   Zgettext_auto_buildrh   infor   r   r   lenr3   	verbosityZwrite_molanguageZ gettext_allow_fuzzy_translations)rD   rn   ro   rt   catalogrE   rM   rF   compile_catalogs   s     

zBuilder.compile_catalogsc                 C  sH   t | j| jj| jj| jj}tdtt|j	 }| 
t|j	| d S )Nzall of %d po files)r   r6   r<   locale_dirsrz   source_encodingr   rx   listrn   r|   set)rD   reporo   rE   rE   rF   compile_all_catalogs   s     zBuilder.compile_all_catalogs)specified_filesr5   c                   s   ddd fdd}t  }t t||}t j jj jj jj}|jD ] }|j	|krJ|
 rJ|| qJtdt| } || d S )NrQ   rR   )fpathr5   c                   s,    j t| }|r$t| jjS d S d S rq   )r4   path2docr   abspathr   r<   Zgettext_compact)r   rS   rM   rE   rF   	to_domain   s    z4Builder.compile_specific_catalogs.<locals>.to_domainz*targets for %d po files that are specified)r   mapr   r6   r<   r}   rz   r~   rn   domainis_outdatedr>   r   rx   r|   )rD   r   r   rn   domainsr   r{   ro   rE   rM   rF   compile_specific_catalogs   s     
z!Builder.compile_specific_catalogsc                 C  sL   t | j| jj| jj| jj}dd |jD }tdt| }| 	|| d S )Nc                 S  s   h | ]}|  r|qS rE   )r   ).0crE   rE   rF   	<setcomp>   s      z2Builder.compile_update_catalogs.<locals>.<setcomp>z,targets for %d po files that are out of date)
r   r6   r<   r}   rz   r~   rn   r   rx   r|   )rD   r   rn   ro   rE   rE   rF   compile_update_catalogs   s     zBuilder.compile_update_catalogsc                 C  s    |    | jdtddd dS )zBuild all source files.Nzall source filesall)summarymethod)r   buildr   rM   rE   rE   rF   	build_all   s    zBuilder.build_all)	filenamesr5   c                 C  s   g }|D ]z}t t |}t |s8ttd| q|| jsVttd| q| j	
|}|sxttd| q|| q| | | j|dtdt| d dS )z>Only rebuild as much as needed for changes in the *filenames*.z.file %r given on command line does not exist, zIfile %r given on command line is not under the source directory, ignoringz?file %r given on command line is not a valid document, ignoringZspecificz%%d source files given on command line)r   r   N)r   normpathr   isfilerh   ri   r   
startswithr6   r4   r   appendr   r   rx   )rD   r   docnamesfilenamerS   rE   rE   rF   build_specific   s0    




zBuilder.build_specificc                 C  sP   |    |  }t|tr*| dg| n"t|}| j|tdt| d dS )z8Only rebuild what was changed or added since last build.__all__z0targets for %d source files that are out of date)r   N)r   r[   
isinstancerQ   r   r   r   rx   )rD   Zto_buildrE   rE   rF   build_update  s    
zBuilder.build_updateupdatezIterable[str] | None)r   r   r   r5   c           
   
   C  s  |r t ttd| j |  t  t|  }W 5 Q R X t	|}t jttddd | j
| j|D ]}|| qnt	|| }|rt td| nt td |r8ddlm} ttd	8 tt| j|d
}	t| j
|	tj W 5 Q R X W 5 Q R X tj| j_ttd | j
  W 5 Q R X n&|dkr^|s^t ttd dS tj| j_|r|dgkrt|| j
j@ }tr| jjdkr| j r| j!d| _"nd| _"t# | _$| %|t&|| | '  | j$  dS )zjMain build method.

        First updates the environment, and then calls
        :meth:`!write`.
        zbuilding [%s]: z"looking for now-outdated files... TZnonlz%d foundz
none foundr   )ENV_PICKLE_FILENAMEzpickling environmentwbzchecking consistencyr   zno targets are out of date.Nr   rc   writeF)(rh   rw   r   r   r@   r   pending_warningsr   readrx   r4   Zcheck_dependentsr3   r>   sphinx.applicationr   r   openr   joinr8   pickledumpHIGHEST_PROTOCOLr   ZCONSISTENCY_CHECKphaseZcheck_consistency	RESOLVING
found_docsr'   parallelallow_parallelis_parallel_allowedrB   r%   rC   r   r   finish)
rD   r   r   r   updated_docnamesZdoccountrS   Zoutdatedr   frE   rE   rF   r   &  sB    
&

zBuilder.buildc                 C  s  t jttddd | j| j|  | jjtk}| j	|\}}}| j
d| j|||D ]}|t|| jj@  qZ|s~|r|| jj| jj@  |rt| jjd| jjpd }t jd|dd t tdt|t|t| |D ]"}| j
d| j| | j| qt||B }| j
d	| j| trZt|d
krZ| jjdkrZ| jd}	nd}	|	rx| j|| jjd n
| | | jj| jjkrtd| j| jj | j
d| jD ]}
|
dk	r| |
 qt| j_t|S )z(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).
        zupdating environment: Tr   zenv-get-outdatedr.   z[%s] z %s added, %s changed, %s removedenv-purge-doczenv-before-read-docs   rc   r   Fnproczroot file %s not foundzenv-updatedN)!rh   rw   r   r   r4   
find_filesr<   Zconfig_statusr   Zget_outdated_filesr;   emitr   r   r   Zglob_toctreesr   rf   Zconfig_status_extrarx   	clear_docrg   r'   r3   r   r   _read_parallel_read_serialroot_docall_docsr   doc2pathextend)rD   updatedaddedchangedZremoveddocsreasonrS   r   Zpar_okretvalrE   rE   rF   r   p  sL    

  "

zBuilder.read)r   r5   c                 C  sN   t |tddt|| jjD ],}| jd| j| | j| | 	| qd S )Nreading sources... purpler   )
r   r   rx   r3   ry   r;   r   r4   r   read_doc)rD   r   rS   rE   rE   rF   r     s     zBuilder._read_serialint)r   r   r5   c           	        s   t ||}t|tddt|jj |D ]"}jdj| j	| q*dddfdd}ddd	d
 fdd}t
|}|D ]}|||| q|  td d S )Nr   r   r   r0   bytesr   r5   c                   s2    j  j_ | D ]} j|dd qt jtjS )NF_cache)r3   r4   r   r   dumpsr   )r   rS   rM   rE   rF   read_process  s    
z,Builder._read_parallel.<locals>.read_processr2   )r   otherenvr5   c                   s(   t |}j| |j t  d S rq   )r   loadsr4   Zmerge_info_fromr3   next)r   r   r4   progressrD   rE   rF   merge  s    
z%Builder._read_parallel.<locals>.merger.   )r&   r   r   rx   r3   ry   r;   r   r4   r   r$   add_taskr   rh   rw   )	rD   r   r   chunksrS   r   r   taskschunkrE   r   rF   r     s    
 zBuilder._read_parallelr   bool)rS   r   r5   c             
   C  s  | j | t| jd}t|r0| j | | j |}t| j	j
j|}| j	j| j	|}t |j_t| j L t|| j
j0 tdt| |j|d |  |j}W 5 Q R X W 5 Q R X t d | j j|< | j j  | j j  | j |||d dS )z>Parse a file and add/update inventory entries for the doctree.zdocutils.confsphinx)source_pathi  r   N)!r4   Zprepare_settingsr   r   r7   r   Znote_dependencyr   r   r3   r<   Zsource_suffixrI   Zget_publisherr
   settingsrecord_dependenciesr   r   Zdefault_rolecodecsregister_errorr   Z
set_sourcepublishZdocumenttimetime_nsr   Z	temp_dataclearZref_contextwrite_doctree)rD   rS   r   Zdocutilsconfr   filetypeZ	publisherr]   rE   rE   rF   r     s"    

zBuilder.read_docznodes.document)rS   r]   r   r5   c             	   C  s   d|_ d|_|j |_d|j_d|j_d|j_t| j	|d }t
t| t|d}t||tj W 5 Q R X |r|| jj|< dS )zWrite the doctree to a file.Nz.doctreer   )reporterZtransformerr   copyZwarning_streamr4   r   r   r   r8   r!   dirnamer   r   r   r   Z_write_doc_doctree_cache)rD   rS   r]   r   Zdoctree_filenamer   rE   rE   rF   r     s    zBuilder.write_doctreezSequence[str])build_docnamesr   r   r5   c              	   C  s  |d ks|dgkr| j j}|dkr4t|t|B }nt|}ttddt| t|D ]2}| j j	
|t D ]}|| j jkrt|| qtq^|| jj ttd | | W 5 Q R X ttd |   W 5 Q R X | jr| jt|| jjd d n| t| d S )	Nr   r   zdocnames to write: %sz, zpreparing documentszcopying assetsrc   r   )r4   r   r   rh   debugr   r   rg   r   Zfiles_to_rebuildrf   r>   r<   r   r   prepare_writingcopy_assetsrB   _write_parallelr3   r   _write_serial)rD   r   r   r   r   rS   Z
tocdocnamerE   rE   rF   r     s(    

zBuilder.writec              	   C  st   t  b t|tddt|| jjD ]>}tj| j_	| j
|| }tj| j_	| || | || q&W 5 Q R X d S )Nru   rv   )r   r   r   r   rx   r3   ry   r   r   r   r4   get_and_resolve_doctreeWRITINGwrite_doc_serialized	write_doc)rD   r   rS   r]   rE   rE   rF   r   9  s    
 

zBuilder._write_serialc                   s  dddfdd}|d |dd   }}t jj_j|}t jj_|| || t	|}t
||}t|tdd	t|jj d
ddd fdd}t jj_|D ]H}	g }
|	D ],}j|}|| |
||f q|||
| q|  td d S )Nz list[tuple[str, nodes.document]]r2   r   c                   s(   t j j_| D ]\}} || qd S rq   )r   r   r3   r   r   )r   rS   r]   rM   rE   rF   write_processD  s    
z.Builder._write_parallel.<locals>.write_processr   rc   ru   rv   zlist[tuple[str, NoneType]]r)   )rH   resultr5   c                   s   t   d S rq   )r   )rH   r   )r   rE   rF   on_chunk_doneY  s    z.Builder._write_parallel.<locals>.on_chunk_doner.   )r   r   r3   r   r4   r   r   r   r   r$   r&   r   r   rx   ry   r   r   r   rh   rw   )rD   r   r   r   Z	firstnamer]   r   r   r   r   argrS   rE   r   rF   r   C  s0    


 
zBuilder._write_parallelzset[str]c                 C  s   t dS )z?A place where you can add logic before :meth:`write_doc` is runNrU   )rD   r   rE   rE   rF   r   i  s    zBuilder.prepare_writingc                 C  s   dS )zBWhere assets (images, static files, etc) are copied before writingNrE   rM   rE   rE   rF   r   m  s    zBuilder.copy_assets)rS   r]   r5   c                 C  s   t dS )z5Where you actually write something to the filesystem.NrU   rD   rS   r]   rE   rE   rF   r   q  s    zBuilder.write_docc                 C  s   dS )zoHandle parts of write_doc that must be called in the main process
        if parallel build is active.
        NrE   r   rE   rE   rF   r   u  s    zBuilder.write_doc_serializedc                 C  s   dS )zWFinish the building process.

        The default implementation does nothing.
        NrE   rM   rE   rE   rF   r   {  s    zBuilder.finishc                 C  s   dS )zQCleanup any resources.

        The default implementation does nothing.
        NrE   rM   rE   rE   rF   cleanup  s    zBuilder.cleanup)optiondefaultr5   c                 C  sR   z| j  d| }t| j|W S  tk
rL   | d| }t| j| Y S X dS )zReturn 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.
        _N)r@   getattrr<   AttributeError)rD   r   r   optnamerE   rE   rF   get_builder_config  s    	zBuilder.get_builder_config)N)N)Nr   )r   )0__name__
__module____qualname____doc__r@   r?   epilog__annotations__r9   r:   r   Zuse_message_catalogr1   Zsupported_remote_imagesZsupported_data_uri_imagesrG   rJ   rL   rN   rP   rW   rZ   r[   r\   rm   r|   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r  rE   rE   rE   rF   r-   +   sb   
		
!	  J@"! %
&r-   )Kr  
__future__r   r   r   r   osr   typingr   r   r   r   Zdocutilsr   Zdocutils.nodesr	   Zdocutils.utilsr
   Zsphinx.configr   Zsphinx.environmentr   r   r   Z!sphinx.environment.adapters.assetr   Zsphinx.errorsr   Zsphinx.eventsr   Zsphinx.localer   Zsphinx.utilr   r   r   r   r   Zsphinx.util.build_phaser   Zsphinx.util.consoler   Zsphinx.util.displayr   r   Zsphinx.util.docutilsr   Zsphinx.util.i18nr   r   r   Zsphinx.util.osutilr    r!   r"   r#   Zsphinx.util.parallelr$   r%   r&   r'   Zsphinx.util.tagsr(   Zsphinx.util.typingr)   r   r*   r+   r   r,   	getLoggerr  rh   r-   rE   rE   rE   rF   <module>   s>   
