o NiS/@sdZddlmZddlZddlmZddlmZmZddl m Z ernddl m Z m Z mZmZddlmZdd lmZdd lmZmZdd lmZdd lmZdd lmZddlmZddlmZddl m!Z!ddl"m#Z#m$Z$dZ%GdddZ&GdddZ'dS)zSupport for domains. Domains are groupings of description directives and roles describing e.g. constructs of one programming language. ) annotationsN) TYPE_CHECKING)Index IndexEntry)_)CallableIterableSequenceSet)Any)nodes)ElementNode) Directive)Inliner) pending_xref)Builder)BuildEnvironment)XRefRole) RoleFunction TitleGetter)DomainrrObjTypec@s"eZdZdZddiZdd d Zd S)ra3 An ObjType is the description for a type of object that a domain can document. In the object_types attribute of Domain subclasses, object type names are mapped to instances of this class. Constructor arguments: - *lname*: localized name of the type (do not include domain name) - *roles*: all the roles that can refer to an object of this type - *attrs*: object attributes -- currently only "searchprio" is known, which defines the object's priority in the full-text search index, see :meth:`Domain.get_objects()`. searchpriolnamestrrolesr attrsreturnNonecOs||_||_|j|B|_dSN)rr known_attrsr)selfrrrr$K/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/domains/__init__.py__init__9szObjType.__init__N)rrrr rr rr )__name__ __module__ __qualname____doc__r"r&r$r$r$r%r&s rc@seZdZUdZdZdZiZded<iZded<iZ ded<gZ d ed <iZ d ed <iZ d ed<iZ ded<ded<dZdXddZdYddZdZd d!Zd[d#d$Zd\d&d'Zd]d)d*Zd^d.d/Zd_d2d3ZdYd4d5Zd`d8d9ZdadCdDZdbdFdGZdcdIdJZdddedOdPZdfdSdTZdgdUdVZdWS)hra A Domain is meant to be a group of "object" description directives for objects of a similar nature, and corresponding roles to create references to them. Examples would be Python modules, classes, functions etc., elements of a templating language, Sphinx roles and directives, etc. Each domain has a separate storage for information about existing objects and how to reference them in `self.data`, which must be a dictionary. It also must implement several functions that expose the object information in a uniform way to parts of Sphinx that allow the user to reference or search for objects in a domain-agnostic way. About `self.data`: since all object and cross-referencing information is stored on a BuildEnvironment instance, the `domain.data` object is also stored in the `env.domaindata` dict under the key `domain.name`. Before the build process starts, every active domain is instantiated and given the environment object; the `domaindata` dict must then either be nonexistent or a dictionary whose 'version' key is equal to the domain class' :attr:`data_version` attribute. Otherwise, `OSError` is raised and the pickled environment is discarded. zdict[str, ObjType] object_typeszdict[str, type[Directive]] directivesz"dict[str, RoleFunction | XRefRole]rzlist[type[Index]]indiceszdict[str, str]dangling_warningsz0dict[type[Node], tuple[str, TitleGetter | None]]enumerable_nodesdict initial_datadict[str, Any]datarenvrrr cCs&||_i|_i|_i|_i|_t|j|_t|j|_t|j|_t |j |_ |j |j vrJt |jts5Jt|j}|j|d<||_|j |j <n|j |j |_|jd|jkr`td|j|jD]!\}}|jD] }|j|g|ql|jr|jdnd|j|<qe|jj|_|jj|_dS)Nversionzdata of %r domain out of daterr+)r5 _role_cache_directive_cache _role2type _type2roler1r,r-rlistr.name domaindata isinstancer2copydeepcopy data_versionr4OSErrorlabelitems setdefaultappendgetobjtypes_for_rolerole_for_objtype)r#r5new_datar<objrolenamer$r$r%r&ms.         zDomain.__init__cCsJ|jjj}|jD]}|jr"|jr"|jd|j}|||d|jqdS)zSet up domain object.-r+N)r5domainsstandard_domainr.r< localnamenote_hyperlink_target)r#stdindexdocnamer$r$r%setups   z Domain.setupr<robjtypercCsP||j|<|jr|jd|j|<nd|j|<|jD] }|j|g|qdS)zAdd an object type.rr+N)r,rr:r9rErF)r#r<rVroler$r$r%add_object_types   zDomain.add_object_typeRoleFunction | NonecsXjvr jSjvrdSjd  ddfdd }|j<|S)zReturn a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. N:r$typrrawtexttextlinenointinlinerroptions dict | Nonecontent Sequence[str]r-tuple[list[Node], list[nodes.system_message]]csj|||||p i|Sr!)r)r[r\r]r^r`rarcfullnamer<r#r$r% role_adapters z!Domain.role..role_adapter)Nr$)r[rr\rr]rr^r_r`rrarbrcrdrre)r7rr<)r#r<rhr$rfr%rWs    z Domain.roleCallable | Nonecs^||jvr |j|S||jvrdS|jd||j|}Gfddd|}||j|<|S)zReturn a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. NrZcs eZdZdfdd ZZS)z*Domain.directive..DirectiveAdapterr list[Node]cs|_tSr!)r<superrunr#) __class__rgr$r%rls z.Domain.directive..DirectiveAdapter.run)rrj)r'r(r)rl __classcell__r$rg)rnr%DirectiveAdaptersrq)r8r-r<)r#r< BaseDirectiverqr$rpr% directives     zDomain.directiverTcCdS)z?Remove traces of a document in the domain-specific inventories.Nr$)r#rTr$r$r% clear_doczDomain.clear_docdocnamesSet[str] otherdatacCstd|j)zMerge in data regarding *docnames* from a different domaindata inventory (coming from a subprocess in parallel builds). zLmerge_domaindata must be implemented in %s to be able to do parallel builds!)NotImplementedErrorrn)r#rwryr$r$r%merge_domaindataszDomain.merge_domaindatadocumentnodes.documentcCrt)z7Process a document after it is read by the environment.Nr$)r#r5rTr|r$r$r% process_docszDomain.process_doccCrt)z)Do consistency checks (**experimental**).Nr$rmr$r$r%check_consistencyrvzDomain.check_consistencypnodercCrt)zxProcess a pending xref created in a doc field. For example, attach information about the current scope. Nr$)r#rr$r$r%process_field_xrefszDomain.process_field_xref fromdocnamebuilderrr[targetnodecontnoder Element | NonecCrt)aLResolve the pending_xref *node* with the given *typ* and *target*. This method should return a new node, to replace the xref node, containing the *contnode* which is the markup content of the cross-reference. If no resolution can be found, None can be returned; the xref node will then given to the :event:`missing-reference` event, and if that yields no resolution, replaced by *contnode*. The method can also raise :exc:`sphinx.environment.NoUri` to suppress the :event:`missing-reference` event being emitted. Nr$)r#r5rrr[rrrr$r$r% resolve_xrefzDomain.resolve_xreflist[tuple[str, Element]]cCst)a9Resolve the pending_xref *node* with the given *target*. The reference comes from an "any" or similar role, which means that we don't know the type. Otherwise, the arguments are the same as for :meth:`resolve_xref`. The method must return a list (potentially empty) of tuples ``('domain:role', newnode)``, where ``'domain:role'`` is the name of a role that could have created the same reference, e.g. ``'py:func'``. ``newnode`` is what :meth:`resolve_xref` would return. .. versionadded:: 1.3 )rz)r#r5rrrrrr$r$r%resolve_any_xrefrzDomain.resolve_any_xref-Iterable[tuple[str, str, str, str, str, int]]cCsgS)auReturn an iterable of "object descriptions". Object descriptions are tuples with six items: ``name`` Fully qualified name. ``dispname`` Name to display when searching/linking. ``type`` Object type, a key in ``self.object_types``. ``docname`` The document where it is to be found. ``anchor`` The anchor name for the object. ``priority`` How "important" the object is (determines placement in search results). One of: ``1`` Default priority (placed before full-text matches). ``0`` Object is important (placed before default-priority objects). ``2`` Object is unimportant (placed after full-text matches). ``-1`` Object should not show up in search at all. r$rmr$r$r% get_objectss!zDomain.get_objectsFtypeprimaryboolcCs|r|jStd|j|jfS)z#Return full name for given ObjType.z%s %s)rrrC)r#rrr$r$r% get_type_name'szDomain.get_type_namer str | NonecCs|j|jd\}}|S)z,Get type of enumerable nodes (experimental).)NN)r0rGrn)r#renum_node_typerr$r$r%get_enumerable_node_type-szDomain.get_enumerable_node_typecCrt)z*Return full qualified name for given node.Nr$)r#rr$r$r%get_full_qualified_name2rvzDomain.get_full_qualified_nameN)r5rrr )rr )r<rrVrrr )r<rrrY)r<rrri)rTrrr )rwrxryr3rr )r5rrTrr|r}rr )rrrr )r5rrrrrr[rrrrrrr rr)r5rrrrrrrrrrr rr)rr)F)rrrrrr)rrrr)rr rr)r'r(r)r*r<rCr,__annotations__r-rr.r/r0r2rAr&rUrXrWrsrur{r~rrrrrrrrr$r$r$r%r?s:                    # r)(r* __future__rr?typingrsphinx.domains._indexrr sphinx.localercollections.abcrrr r r docutilsr docutils.nodesr rdocutils.parsers.rstrdocutils.parsers.rst.statesrsphinx.addnodesrsphinx.buildersrsphinx.environmentr sphinx.rolesrsphinx.util.typingrr__all__rrr$r$r$r%s*