o $azc@sdZddlZddlZddlmZddlmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZddlmZddlmZddlmZmZmZdd lmZdd lmZdd lm Z dd l!m"Z"dd l#m$Z$ddl%m&Z&m'Z'm(Z(m)Z)m*Z*ddl+m,Z,ddl-m.Z.ddl/m0Z0ddl1m2Z2m3Z3m4Z4ddl5m6Z6m7Z7m8Z8m9Z9ddl:m;Z;mZ>ddl?m@Z@ddlAmBZBddlAmCZCzddlDZDWn eEydZDYnwerddlFmGZGe'HeIZJGdddZKdS)z sphinx.builders ~~~~~~~~~~~~~~~ Builder superclass for all builders. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N)path) TYPE_CHECKINGAnyDictIterableListOptionalSequenceSetTupleTypeUnion)nodes)Node)Config)CONFIG_CHANGED_REASON CONFIG_OKBuildEnvironment) ImageAdapter) SphinxError) EventManager)read_doc)__) import_objectloggingprogress_messagerststatus_iterator) BuildPhase)bold)sphinx_domains) CatalogInfoCatalogRepositorydocname_to_domain)SEP ensuredir relative_urirelpath) ParallelTasks SerialTasks make_chunksparallel_available)Tags) directives)roles)Sphinxc @seZdZUdZdZdZdZdZee j e d<dZ dZ dZdZgZeee d<dZdZdbd d Zded dfddZded ee j fddZded e j fddZdcddZdcddZdddeded efddZdddededed efd d!Zd eee effd"d#Z!d eefd$d%Z"d&e#d dfd'd(Z$d)e%e&d*ed dfd+d,Z'dcd-d.Z(d/eed dfd0d1Z)dcd2d3Z*dcd4d5Z+d6eed dfd7d8Z,dcd9d:Z-deded dfd?d@Z.d eefdAdBZ/ded dfdNdOZ7dd^ed_ed efd`daZ?dS)gBuilderz6 Builds target formats from the reST sources. Ndefault_translator_classnoneFTsupported_image_typesappr/returncCs|j|_|j|_|j|_|j|_t|j||_d|_|j|_|j|_|j |_ |j |j |j |j |j d|j |j d|j i|_ d|_d|_d|_d|_dS)Nz format_%sz builder_%sr1F)srcdirconfdiroutdir doctreedirr%r5enveventsconfigtagsaddformatnameimagesimagedirimgpath parallel_ok finish_tasks)selfr5rH:/usr/lib/python3/dist-packages/sphinx/builders/__init__.py__init__Ts&  zBuilder.__init__r;cCs||_|j|j|jdS)zStore BuildEnvironment object.N)r;set_versioning_methodversioning_methodversioning_compare)rGr;rHrHrIset_environmentps zBuilder.set_environmentargscGs|jj|S)zReturn a class of translator.)r5registryget_translator_classrGrOrHrHrIrQvszBuilder.get_translator_classcGs|jjj|g|RS)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. )r5rPcreate_translatorrRrHrHrIrSzszBuilder.create_translatorcCdS)zoLoad necessary templates and perform initialization. The default implementation does nothing. NrHrGrHrHrIinitz Builder.initcCs6|jjrt|jjd|_dSddlm}||_dS)z&Return the template bridge configured.ztemplate_bridge settingr)BuiltinTemplateLoaderN)r=template_bridger templatessphinx.jinja2gluerX)rGrXrHrHrIcreate_template_bridges   zBuilder.create_template_bridgedocnametypcCt)zReturn the target URI for a document name. *typ* can be used to qualify the link characteristic for individual builders. NotImplementedError)rGr]r^rHrHrIget_target_uriszBuilder.get_target_urifrom_tocCst|||||S)zReturn a relative URI between two source filenames. May raise environment.NoUri if there's no way to return a sensible URI. )r&rb)rGrcrdr^rHrHrIget_relative_uris  zBuilder.get_relative_uricCr_)aDReturn 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. r`rUrHrHrIget_outdated_docsszBuilder.get_outdated_docscCsgS)z;Return list of paths for assets (ex. templates, CSS, etc.).rHrUrHrHrIget_asset_pathszBuilder.get_asset_pathsdoctreecCst|j}|tjD]f}d|dvrq d|dvr[|jD]}|d|d}|r+n+qt|d}||d}|rIt j t d|j |||dn t j t d|j ||dq ||d<n|d}||jj vrfq |jj |d |j |<q dS) z+Pick the best candidate for all image URIs.? candidates*Nuriz2a suitable image for %s builder not found: %s (%s))locationz-a suitable image for %s builder not found: %s)rr;traverserimager4getsortedget_original_image_uriloggerwarningrrArB)rGrirBnodeimgtype candidate mimetypes image_urirHrHrIpost_process_imagess4          zBuilder.post_process_imagescatalogsmessagecsvjjsdSdtdtffdd }tttd|t|tddt |j j |dD] }| jj jjq,dS) Ncatr6cst|jjjtjtSN)r'mo_pathr;r7replacersepr$)rrUrHrI cat2relpathsz-Builder.compile_catalogs..cat2relpathzbuilding [mo]: writing output... darkgreen)stringify_func)r=gettext_auto_buildr!strruinforrrlenr5 verbositywrite_molanguage gettext_allow_fuzzy_translations)rGr}r~rcatalogrHrUrIcompile_catalogss   zBuilder.compile_catalogscCsHt|j|jj|jj|jj}tdtt|j }| t |j |dS)Nzall of %d po files) r"r7r= locale_dirsrsource_encodingrrlistr}rset)rGrepor~rHrHrIcompile_all_catalogss  zBuilder.compile_all_catalogsspecified_filescsdtdttffdd }t}tt||}tjjjjjjj }|j D]}|j |vr8| r8| |q(tdt|}||dS)Nfpathr6cs(jt|}|rt|jjSdSr)r;path2docrabspathr#r=gettext_compact)rr]rUrHrI to_domainsz4Builder.compile_specific_catalogs..to_domainz*targets for %d po files that are specified)rrrmapr"r7r=rrrr}domain is_outdatedr?rrr)rGrrr}domainsrrr~rHrUrIcompile_specific_catalogss    z!Builder.compile_specific_catalogscCsLt|j|jj|jj|jj}dd|jD}tdt|}| ||dS)NcSsh|]}|r|qSrH)r).0crHrHrI sz2Builder.compile_update_catalogs..z,targets for %d po files that are out of date) r"r7r=rrrr}rrr)rGrr}r~rHrHrIcompile_update_catalogss  zBuilder.compile_update_catalogscCs|jdtddddS)zBuild all source files.Nzall source filesall)summarymethod)buildrrUrHrHrI build_allszBuilder.build_all filenamescCst|jd}g}t|jj}|D]N}tt|}||js*t t d|qt |s8t t d|q||d}|D]}| |rR|dt| }nq@|tjt}||q|j|dt dt|ddS)z>Only rebuild as much as needed for changes in the *filenames*.rozIfile %r given on command line is not under the source directory, ignoringz6file %r given on command line does not exist, ignoringNspecificz%%d source files given on command line)rr)rr7tupler= source_suffixrnormpathr startswithrurvrisfileendswithrrr$appendr)rGrdirlento_writesuffixesfilenamesuffixrHrHrIbuild_specifics4         zBuilder.build_specificcCsJ|}t|tr|dg|dSt|}|j|tdt|ddS)z8Only rebuild what was changed or added since last build.__all__z0targets for %d source files that are out of date)rN)rf isinstancerrrrr)rGto_buildrHrHrI build_updates  zBuilder.build_updateupdatedocnamesrrc Cs,|rtttd|j|tt|}Wdn1s%wYt |}tjttddd|j |j |D]}| |qAt ||}|rZttd|nttd|rdd lm}ttd +tt|j|d } t|j | tjWdn1swYWdn1swYtj|j _ttd  |j Wdn1swYn|d kr|stttddStj|j _|r|dgkrt||j j@}tr|j jdkr|j r|j !d|_"nd|_"t#|_$|%|t&|||'|j$dS)zaMain build method. First updates the environment, and then calls :meth:`write`. zbuilding [%s]: Nz"looking for now-outdated files... Tnonlz%d foundz none foundr)ENV_PICKLE_FILENAMEzpickling environmentwbzchecking consistencyrzno targets are out of date.rrowriteF)(rurrrrArpending_warningsrreadrr;check_dependentsr5r?sphinx.applicationrropenrjoinr:pickledumpHIGHEST_PROTOCOLrCONSISTENCY_CHECKphasecheck_consistency RESOLVING found_docsr+parallelallow_parallelis_parallel_allowedrEr)rFrrfinish) rGrrrupdated_docnamesdoccountr]outdatedrfrHrHrIr*sN        z Builder.buildc Cstjttddd|j|j||jjtk}|j |\}}}|j d|j|||D] }| t ||jj@q-|s?|rJ| |jj|jj@|rbt|jjd|jjpXd}tjd|ddttdt|t|t||D]}|j d|j||j|qtt||B}|j d |j|trt|d kr|jjd kr|jd } nd } | r|j||jjdn|||jj|jjvrtd|j|jj|j d|jD] } | dur| | 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). zupdating environment: Trzenv-get-outdatedr1z[%s] z %s added, %s changed, %s removed env-purge-doczenv-before-read-docsrorFnproczroot file %s not foundz env-updatedN)!rurrrr; find_filesr= config_statusrget_outdated_filesr<emitrrr glob_toctreesrrrconfig_status_extrar clear_docrsr+r5rr_read_parallel _read_serialroot_docall_docsrdoc2pathextend) rGupdatedaddedchangedremoveddocsreasonr]rpar_okretvalrHrHrIrnsJ      z Builder.readcCsNt|tddt||jjD]}|jd|j||j|| |qdS)Nreading sources... purpler) rrrr5rr<rr;rr)rGrr]rHrHrIrs    zBuilder._read_serialrc s|D]}jdj|j|qdttdtffdd }dttdtddffdd }t|}t||}t |t d d t |j j D] }||||qGttt d |dS) Nrrr6cs.jj_|D]}|qtjtjSr)r5r;rrdumpsr)rr]rUrHrI read_processs  z,Builder._read_parallel..read_processotherenvcs t|}j||jdSr)rloadsr;merge_info_fromr5)rrr;rUrHrImerges z%Builder._read_parallel..mergerrwaiting for workers...)r<rr;rrrbytesr(r*rrrr5radd_taskrurrr) rGrrr]rrtaskschunkschunkrHrUrIrs    zBuilder._read_parallelc Cs|j|t|jd}t|r|j|t|j,t ||j j t |j |j|j |}Wdn1s=wYWdn1sLwYttt|j ||jj|<|jj|jj|||dS)z>Parse a file and add/update inventory entries for the doctree.z docutils.confN)r;prepare_settingsrrr8rnote_dependencyr r default_roler=rr5rmaxtimegetmtimer temp_dataclear ref_context write_doctree)rGr] docutilsconfrirHrHrIrs     zBuilder.read_doccCsd|_d|_d|j_d|j_d|j_t|j|d}t t |t |d}t ||t jWddS1s;wYdS)zWrite the doctree to a file.Nz.doctreer)reporter transformersettingswarning_streamr;record_dependenciesrrr:r%dirnamerrrr)rGr]ridoctree_filenamerrHrHrIr s "zBuilder.write_doctreebuild_docnamesrcCs |dus |dgkr |jj}|dkrt|t|B}nt|}ttddt|t|D]}|jj |tD] }||jjvrG| |q:q/| |j j ttd ||Wdn1sfwY|jr}|jt||jjdddS|t|dS)Nrrzdocnames to write: %sz, zpreparing documentsror)r;rrrudebugrrrsrfiles_to_rebuildrrr?r=rrprepare_writingrE_write_parallelr5r _write_serial)rGrrrrr] tocdocnamerHrHrIrs*       z Builder.writecCst7t|tddt||jjD]}tj|j_ |j ||}tj |j_ | |||||qWddS1s>wYdS)Nrr)rrrrrr5rrrrr;get_and_resolve_doctreeWRITINGwrite_doc_serialized write_doc)rGrr]rirHrHrIrs      "zBuilder._write_serialc sdttttjfddffdd }|d|dd}}tjj_j |}tj j_ || ||t|}t||}tjj_t|tddt|jjD]'}g} t|D]\} } j | } | || | |fq^||| qVtttd |dS) Nrr6cs(tjj_|D] \}}||qdSr)rrr5rr)rr]rirUrHrI write_process!s  z.Builder._write_parallel..write_processrrorrr)rr rrdocumentrrr5rr;rrrrr(r*rrrr enumeraterrrurrr) rGrrr  firstnamerirrrargir]rHrUrIr s*$          zBuilder._write_parallelcCr_)z?A place where you can add logic before :meth:`write_doc` is runr`)rGrrHrHrIr?rhzBuilder.prepare_writingcCr_)z5Where you actually write something to the filesystem.r`rGr]rirHrHrIrCrhzBuilder.write_doccCrT)zoHandle parts of write_doc that must be called in the main process if parallel build is active. NrHr&rHrHrIrGrWzBuilder.write_doc_serializedcCrT)zWFinish the building process. The default implementation does nothing. NrHrUrHrHrIrMzBuilder.finishcCrT)zQCleanup any resources. The default implementation does nothing. NrHrUrHrHrIcleanupTr'zBuilder.cleanupoptiondefaultcCsHzd|j|f}t|j|WSty#d||f}t|j|YSw)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. z%s_%s)rAgetattrr=AttributeError)rGr)r*optnamerHrHrIget_builder_config[s   zBuilder.get_builder_config)r5r/r6N)r6Nr)Nr)r)@__name__ __module__ __qualname____doc__rAr@epilogr2r r NodeVisitor__annotations__rLrMruse_message_catalogr4rrsupported_remote_imagessupported_data_uri_imagesrJrrNrrQrSrVr\rbrer rrfrgrr|r r!rrrrrrrrrrintrrr!r r rrrrrrrr(r.rHrHrHrIr03s\     !     D@$   r0)Lr2rrosrtypingrrrrrrr r r r r docutilsrdocutils.nodesr sphinx.configrsphinx.environmentrrr!sphinx.environment.adapters.assetr sphinx.errorsr sphinx.eventsr sphinx.ior sphinx.localer sphinx.utilrrrrrsphinx.util.build_phasersphinx.util.consolersphinx.util.docutilsr sphinx.util.i18nr!r"r#sphinx.util.osutilr$r%r&r'sphinx.util.parallelr(r)r*r+sphinx.util.tagsr,sphinxr-r.multiprocessing ImportErrorrr/ getLoggerr/rur0rHrHrHrIsB  4