o oaRe@s(UdZddlZddlZddlZddlmZddlmZddlmZddlmZddl m Z m Z m Z m Z mZmZmZmZmZmZmZddlmZdd lmZdd lmZdd lmZdd lmZdd lm Z ddl!m"Z"ddl#m$Z$m%Z%m&Z&m'Z'ddl(m)Z)ddl*m+Z+ddl,m-Z-ddl.m/Z/ddl0m1Z1m2Z2m3Z3ddl4m5Z5ddl6m7Z7m8Z8ddl9m:Z:ddl;mm?Z?ddl@mAZAe3BeCZDddddddddd dddd!dgd"ZEe eFe feGd#<d$ZHd%ZId&ZJd'ZKd(ZLeJe+d)eKe+d*eLe+d+iZMde:d,ZNe eFeeOe ffeGd-<Gd.d/d/ZPdS)0z sphinx.environment ~~~~~~~~~~~~~~~~~~ Global creation environment. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N) defaultdict)copy)datetime)path) TYPE_CHECKINGAnyCallableDict GeneratorIteratorListOptionalSetTupleUnion)nodes)Node)addnodes)Config)RemovedInSphinx60Warning)Domain)TocTree)BuildEnvironmentError DocumentErrorExtensionError SphinxError) EventManager)__)Project)SphinxTransformer) DownloadFilesFilenameUniqDictlogging)LoggingReporter)CatalogRepositorydocname_to_domain)is_translatable) canon_pathos_path)Sphinx)BuilderidFTz https://www.python.org/dev/peps/zhttps://tools.ietf.org/html/z utf-8-sig)auto_id_prefix embed_imagesembed_stylesheetcloak_email_addresses pep_base_urlpep_references rfc_base_urlrfc_referencesinput_encodingdoctitle_xformsectsubtitle_xformsection_self_link halt_levelfile_insertion_enabledsmartquotes_localesdefault_settings8z new configzconfig changedzextensions changed)nonetextversioning_conditionsc@seZdZUdZeeefed<d_d`ddZdefd d Z d eddfd d Z daddZ de ddfddZ de ddfddZdeeefdeddfddZdeddfddZdeeddddddfddZd edeefd!d"Zdbded$edefd%d&Zd_d ededeeeffd'd(Zedeefd)d*Zde d+d,ddfd-d.Zd/edeeeeeeeffd0d1Zddd2eede eddffd3d4Z!deddfd5d6Z"edefd7d8Z#dcd:ede$fd;d<Z%d eddfd=d>Z&d eddfd?d@Z'dddAdBZ(dCedefdDdEZ)dede*j+fdFdGZ, # Hdeded+d,dIe*j+dJedKede*j+f dLdMZ- H Hdfded+d,dOe.j/dPedQe$dRedSedKede0fdTdUZ1dIe*j+dVed+d,ddfdWdXZ2dIe*j+deddfdYdZZ3deeeeeffd[d\Z4ddd]d^Z5dS)gBuildEnvironmentz The environment in which the ReST files are translated. Stores an inventory of cross-file targets and provides doctree transformations to resolve links to them. domainsNappr)cCsd|_d|_d|_d|_d|_d|_d|_d|_d|_d|_ d|_ i|_ t |_||jd<i|_tt|_tt|_t|_tt|_i|_i|_i|_i|_i|_i|_i|_i|_t|_t|_ i|_!t"|_#t$|_%i|_&i|_'i|_(|r|)|dSt*j+dt,dddS)Nenvz?The 'app' argument for BuildEnvironment() becomes required now.r?) stacklevel)-rG doctreedirsrcdirconfig config_statusconfig_status_extraeventsprojectversionversioning_conditionversioning_comparerFr<rsettingsall_docsrset dependenciesincluded reread_alwaysdictmetadatatitles longtitlestocstoc_num_entriestoc_secnumberstoc_fignumberstoctree_includesfiles_to_rebuild glob_toctreesnumbered_toctrees domaindatar!imagesr dlfilesoriginal_image_uri temp_data ref_contextsetupwarningswarnr)selfrGrp=/usr/lib/python3/dist-packages/sphinx/environment/__init__.py__init__csP      zBuildEnvironment.__init__returncCs|j}|jdidd|S)z'Obtains serializable data for pickling.N)rGrFrO)__dict__rupdate)rortrprprq __getstate__s zBuildEnvironment.__getstate__statecCs|j|dSN)rtru)rorwrprprq __setstate__szBuildEnvironment.__setstate__cCs|jr|j|j|krttd|jr!|j|jkr!ttd|jr+|j|j||_|j |_ |j |_ |j|_|j|_|j||_i|_ |j |D]}||j |j <qN|j D]}|q\||j||jdS)zSet up BuildEnvironment object.z%build environment version not currentzsource directory has changedN)rQregistryget_envversionrrrKrPrestorerGrJrOrFcreate_domainsnamevaluesrl_update_configrL_update_settings)rorGdomainrprprqrls&    zBuildEnvironment.setuprLcCst|_d|_|jdurt|_nM|jj|jkr?t|_tt|jjt|jA}t |dkr1|d}ndt |f}d|f|_n| dD]}|j|j |j kr[t |_d|j f|_nqD||_dS)z!Update configurations by new one.Nr>rz%dz (%r)rH) CONFIG_OKrMrNrL CONFIG_NEW extensionsCONFIG_EXTENSIONS_CHANGEDsortedrVlenfilterr~valueCONFIG_CHANGED)rorLr extensionitemrprprqrs(    zBuildEnvironment._update_configcCs:|j|jd<|j|jd<|jpd|jd<|jdddS)zUpdate settings by new config.r5trim_footnote_reference_spaceen language_code smart_quotesTN)source_encodingrTrlanguage setdefault)rorLrprprqrs  z!BuildEnvironment._update_settingsmethodcomparecCsTt|r|}n|tvrtd|t|}|jd|fvr"ttd||_||_dS)aXThis sets the doctree versioning method for this environment. Versioning methods are a builder property; only builders with the same versioning method can share the same doctree directory. Therefore, we raise an exception if the user tries to use an environment with an incompatible versioning method. zinvalid versioning method: %rNzdThis environment is incompatible with the selected builder, please choose another doctree directory.)callablerD ValueErrorrRrrrS)rorr conditionrprprqset_versioning_method s    z&BuildEnvironment.set_versioning_methoddocnamecCsP||jvr|j|d|j|d|j||jD]}||qdS)z4Remove all traces of a source file in the inventory.N)rUpoprXrYdiscardrFr clear_doc)rorrrprprqr$s   zBuildEnvironment.clear_docdocnamesothercCst|}|D]}|j||j|<|j||j|<||jvr#|j|q|jD] \}}|||j|q)|j d|||dS)zMerge global information gathered about *docnames* while reading them from the *other* environment. This possibly comes from a parallel build process. zenv-merge-infoN) rVrUrXrYaddrFitemsmerge_domaindatarfrOemit)rorrrGr domainnamerrprprqmerge_info_from.s  z BuildEnvironment.merge_info_fromfilenamecCs |j|S)zReturn the docname for the filename if the file is document. *filename* should be absolute or relative to the source directory. )rPpath2docrorrprprqr@s zBuildEnvironment.path2docTbasecCs|j||S)zReturn the filename for the document name. If *base* is True, return absolute path under self.srcdir. If *base* is False, return relative path to self.srcdir. )rPdoc2path)rorrrprprqrGszBuildEnvironment.doc2pathcCstt|}|ds|tjr|dd}nt|j|p|jdd}t||}t t |t t|j |fS)a+Return paths to a file referenced from a document, relative to documentation root and absolute. In the input "filename", absolute filenames are taken as relative to the source dir, while relative filenames are relative to the dir of the containing document. /r>N)r) r( startswithosseprdirnamerrjoinr'normpathrK)rorrrel_fndocdirrprprq relfn2pathOs  zBuildEnvironment.relfn2pathcCs|jjS)zcontains all existing docnames.)rPrrorprprq found_docsbszBuildEnvironment.found_docsbuilderr*c CszL|jj|jj|}|j||jrGt|j|jj |jj |jj }dd|j D}|j D]}t||jj}||vrF|j|||q/WdSWdStyd}z ttd|j|f|d}~ww)zYFind all source files in the source dir and put them in self.found_docs. cSsi|]}|j|jqSrp)rmo_path).0crprprq {sz/BuildEnvironment.find_files..z"Failed to scan documents in %s: %rN)rLexclude_patternstemplates_pathget_asset_pathsrPdiscoveruse_message_catalogr$rK locale_dirsrrcatalogsrr%gettext_compactrWrOSErrorrr) rorLr exclude_pathsrepomo_pathsrrexcrprprq find_filesgs6    zBuildEnvironment.find_filesconfig_changedc Cs|t|j|j}t}t}|r|j}n|jD]}||jvr*td|||qt|j|d}t |sDtd|||q||j vrUtd|||q|j|}t | |}||krztd|t |t |||q|j|D]8} z't|j| } t | s||Wn"t | } | |kr||WnWqty||Ynwq|||fS)z&Return (added, changed, removed) sets.z[build target] added %r.doctreez[build target] changed %rz$[build target] outdated %r: %s -> %s)rVrUrloggerdebugrrrrJisfilerYgetmtimerrutcfromtimestamprWrKr) rorremovedaddedchangedrrmtimenewmtimedepdeppathdepmtimerprprqget_outdated_filess\                   z#BuildEnvironment.get_outdated_filesalreadyccsDg}|jd|D]}||q t|D] }||vr|VqdS)Nzenv-get-updated)rOrextendrV)rorGr to_rewriterrrprprqcheck_dependentss  z!BuildEnvironment.check_dependentscCs2||jd<|jj|jd<|j|jj|jd<dS)z*Prepare to set up environment for reading.r default_roledefault_domainN)rjrLrrFgetprimary_domain)rorrprprqprepare_settingss  z!BuildEnvironment.prepare_settingscCs |jdS)z;Returns the docname of the document currently being parsed.r)rjrrprprqrs zBuildEnvironment.docnamercategorycCs(|d}|j|d}|d|j|<|S)zReturn a serial number, e.g. for index entry targets. The number is guaranteed to be unique in the current document. serialnorr>)rjr)rorkeycurrprprq new_serialnoszBuildEnvironment.new_serialnocCs|j|j|dS)zAdd *filename* as a dependency of the current document. This means that the document will be rebuilt if this file changes. *filename* should be absolute or relative to the source directory. N)rWrrrrprprqnote_dependencysz BuildEnvironment.note_dependencycCs|j|j||dS)zAdd *filename* as a included from other document. This means the document is not orphaned. *filename* should be absolute or relative to the source directory. N)rXrrrrrprprq note_includedszBuildEnvironment.note_includedcCs|j|jdS)zxAdd the current document to the list of documents that will automatically be re-read at the next build. N)rYrrrrprprq note_rereadszBuildEnvironment.note_rereadrc Cs8z|j|WSty}z ttd||d}~ww)zReturn the domain instance with the specified name. Raises an ExtensionError if the domain is not registered. zDomain %r is not registeredN)rFKeyErrorrr)rorrrprprq get_domains  zBuildEnvironment.get_domaincCsbt|j|d}t|d }t|}Wdn1swY||j_t| ||_ |S)z:Read the doctree for a file from the pickle and return it.rrbN) rrrJopenpickleloadrTrHr#rreporter)rorrfdoctreerprprq get_doctrees  zBuildEnvironment.get_doctreeFrprune_toctrees includehiddencCsj|dur ||}||||tjD]}t|j|||||d}|dur-|gq||q|S)zgRead the doctree from the pickle, resolve cross-references and toctrees and return it. N)pruner)rapply_post_transformstraversertoctreerresolve replace_self)rorrrrr toctreenoderesultrprprqget_and_resolve_doctree s    z(BuildEnvironment.get_and_resolve_doctreerrrmaxdepth titles_onlycollapsec Cst|||||||||S)aResolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node. If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0, to the value of the *maxdepth* option on the *toctree* node. If *titles_only* is True, only toplevel document titles will be in the resulting tree. If *collapse* is True, all branches not containing docname will be collapsed. )rr) rorrrrrrrrrprprqresolve_toctree%sz BuildEnvironment.resolve_toctree fromdocnamecCs|||dSrx)r)rorrrrprprqresolve_references7sz#BuildEnvironment.resolve_referencescCshz%t|j}||jd<t|}||||jj|W||_n||_w|j d||dS)zApply all post-transforms.rzdoctree-resolvedN) rrjrset_environmentadd_transformsrGrzget_post_transformsapply_transformsrOr)rorrbackup transformerrprprqr;s    z&BuildEnvironment.apply_post_transformsc stdtdtdttttfffdd i}djj}d}t|\}}|D]\}}|||g||<|}|}|}q+||dg||<|S)Nparentrrsc3s||krtjtd|ddddS||fV|j|p#gD]}||D]\}}|vr=||fV|q+q$dS)Nz'self referenced toctree found. Ignored.toccircular)locationtypesubtype)rwarningrrrbr)rrchild subparent subdocnamerotraverse_toctree traversedrprqrOs"     z.traverse_toctree)rVstrr rrLroot_docnext)ro relationsrprevdocrr nextparentnextdocrprrqcollect_relationsLs*  z"BuildEnvironment.collect_relationscCstj|j}t|jD]$}||jvr2||jjkrq||vr!qd|j |vr)qt j t d|dq|j D]}|q8|jd|dS)zDo consistency checks.orphanz&document isn't included in any toctree)rzenv-check-consistencyN)rVunionrXrrrUrcrLrr[rrrrFcheck_consistencyrOr)rorXrrrprprqr%ns     z"BuildEnvironment.check_consistencyrx)rGr))rGr)rsN)T)r)rsN)NTF)TrFFF)6__name__ __module__ __qualname____doc__r rr__annotations__rrrvryrlrrrrrboolrrr rr rrrrpropertyrrrrr rrrintrrrrrrdocumentrrrrrrrrr"r%rprprprqrEXs  ^      ($9          "rE)Qr)rrrm collectionsrrrrtypingrrrr r r r r rrrdocutilsrdocutils.nodesrsphinxr sphinx.configrsphinx.deprecationrsphinx.domainsr#sphinx.environment.adapters.toctreer sphinx.errorsrrrr sphinx.eventsr sphinx.localersphinx.projectrsphinx.transformsr sphinx.utilr r!r"sphinx.util.docutilsr#sphinx.util.i18nr$r%sphinx.util.nodesr&sphinx.util.osutilr'r(sphinx.applicationr)sphinx.buildersr* getLoggerr&rr<rr* ENV_VERSIONrrrrCONFIG_CHANGED_REASONrDr+rErprprprqsv     4