o Ni@sdZddlmZddlZddlZddlZddlZddlmZddl m Z ddl m Z m Z mZmZddlmZddlmZdd lmZmZmZdd lmZdd lmZdd lmZdd lmZm Z m!Z!ddl"m#Z#ddl$m%Z%ddl&m'Z'ddl(m)Z)m*Z*ddl+m,Z,ddl-m.Z.m/Z/m0Z0ddl1m2Z2m3Z3m4Z4m5Z5m6Z6ddl7m8Z8m9Z9m:Z:m;Z;ddlZ>e rddl?m@Z@mAZAmBZBddlCmDZDddlEmFZFddlGmHZHddlImJZJddlKmLZLe MeNZOGdddZPGd d!d!ZQdS)"z$Builder superclass for all builders.) annotationsN) nullcontext)path) TYPE_CHECKINGAnyLiteralfinal)nodes)DependencyList)CONFIG_CHANGED_REASON CONFIG_OKBuildEnvironment) ImageAdapter) SphinxError)__) get_filetypeloggingrst) import_object) BuildPhase)bold)progress_messagestatus_iterator)sphinx_domains) CatalogInfoCatalogRepositorydocname_to_domain)SEP canon_path ensuredir relative_urirelpath) ParallelTasks SerialTasks make_chunksparallel_available) directives)roles)IterableSequenceSet)Node)Sphinx)Config) EventManager)Tagsc@seZdZUdZdZded<dZded<dZded<ded<d Zd Z d Z d ed <d Z gZ ded<d Z d ed<d Zd ed<d~ddZdddZddd Zdd!d"Zdd#d$Zddd)d*Zddd-d.Zdd0d1Zdd2d3Zdd6d7Zdd;d<Zdd=d>Zdd@dAZddBdCZeddDdEZeddGdHZeddIdJZ e % KdddQdRZ!eddSdTZ"ddUdVZ#ddYdZZ$ed d[dd]d^Z%ed d[dd`daZ&e KdddedfZ'ddhdiZ(ddjdkZ)ddldmZ*ddndoZ+ddpdqZ,ddrdsZ-ddtduZ.ddvdwZ/ddxdyZ0dd|d}Z1d%S)Builderz6 Builds target formats from the reST sources. strnameformatepilogtype[nodes.NodeVisitor]default_translator_classnoneFboolallow_parallelT list[str]supported_image_typessupported_remote_imagessupported_data_uri_imagesappr,envr returnNonecCs|j|_|j|_|j|_|j|_t|j||_||_|j|j|j |j |_ |j |_ |j |_ |j |j|j |j|j d|j|j d|ji|_d|_d|_d|_d|_dS)Nformat_builder_r1F)srcdirconfdiroutdir doctreedirrr?r@set_versioning_methodversioning_methodversioning_compareeventsconfigtagsaddr4r3imagesimagedirimgpath parallel_ok finish_tasks)selfr?r@rVL/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/builders/__init__.py__init__`s(  zBuilder.__init__argsrcGs|jj|S)zReturn a class of translator.)r?registryget_translator_classrUrYrVrVrWr[}szBuilder.get_translator_classnodes.NodeVisitorcGs|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. )r?rZcreate_translatorr\rVrVrWr^szBuilder.create_translatorcCdS)zoLoad necessary templates and perform initialization. The default implementation does nothing. NrVrUrVrVrWinitz Builder.initcCs<|jjrt|jjdd}||_dSddlm}||_dS)z&Return the template bridge configured.ztemplate_bridge setting)sourcer)BuiltinTemplateLoaderN)rMtemplate_bridger templatessphinx.jinja2gluerd)rUtemplate_bridge_clsrdrVrVrWcreate_template_bridges   zBuilder.create_template_bridgeNdocnametyp str | NonecCt)zReturn the target URI for a document name. *typ* can be used to qualify the link characteristic for individual builders. NotImplementedError)rUrjrkrVrVrWget_target_uriszBuilder.get_target_urifrom_tocCst|||||S)zReturn a relative URI between two source filenames. :raises: :exc:`!NoUri` if there's no way to return a sensible URI. )r rp)rUrqrrrkrVrVrWget_relative_uris zBuilder.get_relative_uristr | Iterable[str]cCrm)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. rnr`rVrVrWget_outdated_docsszBuilder.get_outdated_docscCsgS)z;Return list of paths for assets (ex. templates, CSS, etc.).rVr`rVrVrWget_asset_pathszBuilder.get_asset_pathsdoctreer+cCst|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@findallr imager<getsortedget_original_image_uriloggerwarningrr3rP)rUrxrPnodeimgtype candidate mimetypes image_urirVrVrWpost_process_imagessB       zBuilder.post_process_imagescatalogsset[CatalogInfo]messagecsnjjsdSd fdd }tttd|t|tdd t|jj |d D] }| jj jj q(dS) NcatrrAr2cst|jjjtjtSN)r!mo_pathr@rEreplacersepr)rr`rVrW cat2relpathsz-Builder.compile_catalogs..cat2relpathzbuilding [mo]: writing output... darkgreen)stringify_func)rrrAr2) rMgettext_auto_buildrinforrrlenr? verbositywrite_molanguage gettext_allow_fuzzy_translations)rUrrrcatalogrVr`rWcompile_catalogss   zBuilder.compile_catalogscCsHt|j|jj|jj|jj}tdtt|j }| t |j |dS)Nzall of %d po files) rrErM locale_dirsrsource_encodingrrlistrrset)rUreporrVrVrWcompile_all_catalogsszBuilder.compile_all_catalogsspecified_filescsdfdd }t}tt||}tjjjjjjj}|jD]}|j |vr2| r2| |q"t dt |}||dS) Nfpathr2rArlcs(jt|}|rt|jjSdSr)r@path2docrabspathrrMgettext_compact)rrjr`rVrW to_domainsz4Builder.compile_specific_catalogs..to_domainz*targets for %d po files that are specified)rr2rArl)rmaprrErMrrrrdomain is_outdatedrOrrr)rUrrrdomainsrrrrVr`rWcompile_specific_catalogss  z!Builder.compile_specific_catalogscCsLt|j|jj|jj|jj}dd|jD}tdt|}| ||dS)NcSsh|]}|r|qSrV)r).0crVrVrW "sz2Builder.compile_update_catalogs..z,targets for %d po files that are out of date) rrErMrrrrrrr)rUrrrrVrVrWcompile_update_catalogsszBuilder.compile_update_catalogscCs ||jdtddddS)zBuild all source files.Nzall source filesall)summarymethod)rbuildrr`rVrVrW build_all(szBuilder.build_all filenamescCsg}|D]?}tt|}t|sttd|q|t|j s-ttd|q|j |}|s>ttd|q| |q| ||j|dtdt|ddS)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, ignoringspecificz%%d source files given on command line)rrN)rnormpathrisfilerrr startswithr2rEr@rappendrrr)rUrdocnamesfilenamerjrVrVrWbuild_specific/s@     zBuilder.build_specificcCsR||}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)rru isinstancer2rrrr)rUto_buildrVrVrW build_update\s  zBuilder.build_updateupdaterIterable[str] | Nonerr$Literal['all', 'specific', 'update']c Cs.|rtttd||j|jjrtnt t | }Wdn1s+wYt |}tjttddd| |j|j|t ||}|r[ttd|nttd|rdd lm}ttd +tt|j|d }t|j|tjWdn1swYWdn1swYtj|j_ttd  |jWdn1swYn|d kr|stttddStj|j_|r|dgkrt ||jj@}t r|jj!dkr|j"r|j#d|_$nd|_$t%|_&|'|t(|||)|j&dS)zMain build method, usually called by a specific ``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.rrwriteF)*rrrrr3r?_exception_on_warningrrpending_warningsrreadrrr@check_dependentssphinx.applicationrropenrjoinrHpickledumpHIGHEST_PROTOCOLrCONSISTENCY_CHECKphasecheck_consistency RESOLVING found_docsr%parallelr:is_parallel_allowedrSr#rTrrfinish) rUrrrupdated_docnamesdoccountoutdatedrfrVrVrWrlsX        z Builder.buildcstjttddd|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|tr|jjd kr|jd } nd } | r|j||jjd n|||jj|jjvr>ddlm} ddl m!|j"|jj} t#| | D]} t$%| sqtd} t&| | | f|jj'D]} t$%| sqtd} t&| | | ft |jj(dhkr4t)fdd|jj(Ds4td} t&| | |jj(ftd} t&| | |j d|jD] }|durR|*|qFt|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-docsrrFnprocr) EXCLUDE_PATHS)_translate_patternzSphinx is unable to load the master document (%s) because it matches a built-in exclude pattern %r. Please move your master document to a different location.zSphinx is unable to load the master document (%s) because it matches an exclude pattern specified in conf.py, %r. Please remove this pattern from conf.py.z**c3s |] }t|VqdSr)rematch)rpatrmaster_doc_canonrVrW s  zBuilder.read..zSphinx is unable to load the master document (%s) because it is not included in the custom include_patterns = %r. Ensure that a pattern in include_patterns matches the master document.zSphinx is unable to load the master document (%s). The master document must be within the source directory or a subdirectory of it.z env-updatedN)+rrrrr@ find_filesrM config_statusr get_outdated_filesrLemitrrr glob_toctreesr rconfig_status_extrar clear_docrr%r?rr_read_parallel _read_serial master_docall_docssphinx.projectrsphinx.util.matchingrdoc2pathrrrrexclude_patternsinclude_patternsanyextend)rUupdatedaddedchangedremoveddocsreasonrjrpar_okrmaster_doc_pathrmsgretvalrVrrWrs        "    z Builder.readcCsNt|tddt||jjD]}|jd|j||j|| |qdS)Nreading sources... purpler) rrrr?rrLrr@rread_doc)rUrrjrVrVrWr,s  zBuilder._read_serialrintc st||}t|tddt|jj|D]}jdj|j |qdfdd }dfd d }t |}|D] }| |||q<| t ddS)Nrrrrr;rAbytescs2jj_|D] }j|ddqtjtjS)NF_cache)r?r@rrdumpsr)rrjr`rVrW read_processGs z,Builder._read_parallel..read_processotherenvrBcs(t|}j||jtdSr)rloadsr@merge_info_fromr?next)rrr@progressrUrVrWmergeNs  z%Builder._read_parallel..merger1)rr;rAr)rr;rrrArB)r$rrrr?rrLrr@rr"add_taskrrr) rUrrchunksrjrrtaskschunkrVrrWr9s zBuilder._read_parallelrrc CsB|j|t|jd}t|r|j|t|j|}t |j j j |}|j j |j |}|j|jjd<t|j_t|j7t||j jt|}td||j|d||j}Wdn1smwYWdn1s|wYtd|jj|<|jj |jj! |j"|||ddS)z>Parse a file and add/update inventory entries for the doctree.z docutils.conf_parsersphinx) source_pathNir)#r@prepare_settingsrrrFrnote_dependencyr2rrr?rM source_suffixrZ get_publisherparser temp_datar settingsrecord_dependenciesrr default_role_UnicodeDecodeErrorHandlercodecsregister_error set_sourcepublishdocumenttimetime_nsrclear ref_context write_doctree) rUrjr docutilsconfrfiletype publisher error_handlerrxrVrVrWr\s2        zBuilder.read_docnodes.documentcCsd|_d|_|j|_d|j_d|j_d|j_t|j |d}t t |t |d}t ||t jWdn1s@wY|rO||jj|<dSdS)z@Write the doctree to a file, to be used as a cache by re-builds.Nz.doctreer)reporter transformerr+copywarning_streamr@r,rrrHrdirnamerrrr_write_doc_doctree_cache)rUrjrxrdoctree_filenamerrVrVrWr8s   zBuilder.write_doctreebuild_docnamesr Sequence[str]cCsB|jd||dus|dgkr|jj}|dkr!t|t|B}nt|}ttddt ||j j h}|D]}|jj |tD] }||jjvrQ||qDq9||O}tt |jj|j_ttd ||Wdn1sywYttdd d  |Wdn1swY||dS) z$Write builder specific output files.z write-startedNrrzdocnames to write: %sz, zpreparing documentszcopying assetsFr)rLrr@rrrdebugrrrrMroot_docfiles_to_rebuildrrOdicttoctree_includesitemsrprepare_writing copy_assetswrite_documents)rUrErrrextrarj tocdocnamerVrVrWrs.      z Builder.writeSet[str]cCs6t|}|jr|j||jjdddS||dS)zWrite all documents in *docnames*. This method can be overridden if a builder does not create output files for each document. rrN)rrS_write_parallelr?r _write_serial)rUrsorted_docnamesrVrVrWrOszBuilder.write_documentscCs|jjrtnt7t|tddt||jjD]}t j |j_ |j ||}t j|j_ ||||||qWddS1sEwYdS)Nrr)r?rrrrrrrrrrrr@get_and_resolve_doctreeWRITINGwrite_doc_serialized write_doc)rUrrjrxrVrVrWrTs$   "zBuilder._write_serialc sdfdd }|d|dd}}tjj_j|}tjj_||||t |}t ||}t |t d d t |jjdfd d }tjj_|D]$} g} | D]} j| }| || | |fqZ||| |qT|tddS)Nr list[tuple[str, nodes.document]]rArBcs(tjj_|D] \}}||qdSr)rrWr?rrY)rrjrxr`rVrW write_processs  z.Builder._write_parallel..write_processrrrrrYresultcs tdSr)r)rYr\)rrVrW on_chunk_dones z.Builder._write_parallel..on_chunk_doner1)rrZrArB)rYrZr\rBrArB)rrr?rr@rVrWrXrYr"r$rrrrrrrrr) rUrrr[ firstnamerxr rr]r!argrjrVrrWrSs6       zBuilder._write_parallelcCr_)z?A place where you can add logic before :meth:`write_doc` is runNrV)rUrrVrVrWrMrwzBuilder.prepare_writingcCr_)zBWhere assets (images, static files, etc) are copied before writingNrVr`rVrVrWrNrwzBuilder.copy_assetscCrm)ab Write the output file for the document :param docname: the :term:`docname `. :param doctree: defines the content to be written. The output filename must be determined within this method, typically by calling :meth:`~.Builder.get_target_uri` or :meth:`~.Builder.get_relative_uri`. rnrUrjrxrVrVrWrYs zBuilder.write_doccCr_)zoHandle parts of write_doc that must be called in the main process if parallel build is active. NrVr`rVrVrWrX*rbzBuilder.write_doc_serializedcCr_)zWFinish the building process. The default implementation does nothing. NrVr`rVrVrWr0zBuilder.finishcCr_)zQCleanup any resources. The default implementation does nothing. NrVr`rVrVrWcleanup7razBuilder.cleanupoptiondefaultcCsLz|jd|}t|j|WSty%|d|}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. _)r3getattrrMAttributeError)rUrcrdoptnamerVrVrWget_builder_config>s  zBuilder.get_builder_config)r?r,r@r rArB)rYrrAr6)rYrrAr])rArBr)rjr2rkrlrAr2)rqr2rrr2rkrlrAr2)rArt)rAr;)rxr+rArB)rrrr2rArB)rr;rArB)rr;rArB)Nr)rrrrlrrrArB)rr;rArB)rr;rrrArB)rjr2rr9rArB)rjr2rxr=rr9rArB)r)rErrrFrrrArB)rrRrArB)rrFrArB)rrFrrrArB)rjr2rxr=rArB)rcr2rdr2rAr)2__name__ __module__ __qualname____doc__r3__annotations__r4r5rJrKr:use_message_catalogr<r=r>rXr[r^rarirprsrurvrrrrrrrrrrrrrrr8rrOrTrSrMrNrYrXrrbrirVrVrVrWr09sv               )    , P  n #% '   +    r0c@s$eZdZdZdddZdd d Zd S)r.z8Custom error handler for open() that warns and replaces.rjr2rArBcCs ||_dSr)rj)rUrjrVrVrWrXRs z#_UnicodeDecodeErrorHandler.__init__errorUnicodeDecodeErrortuple[str, int]cCs|jdd|j}|jd|j}|dkrt|j}|jdd|jd}tjtd|j|d|jd|j|j|j d|j|j ||j |fdd |j fS) N rrz5undecodable source characters, replacing with "?": %rs>>>s<<sT