-Ph/dZddlmZddlZddlmZddlmZmZddl m Z erJddl m Z m Z mZddlmZdd lmZdd lmZmZdd lmZdd lmZdd lmZddlmZddlmZddlm Z ddl!m"Z"m#Z#dZ$GddZ%GddZ&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)_)IterableSequenceSet)Any)nodes)ElementNode) Directive)Inliner) pending_xref)Builder)BuildEnvironment)XRefRole) RoleFunction TitleGetter)DomainrrObjTypec"eZdZdZddiZd d Zd S)ra.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 attrsreturnNonec@||_||_|j|z|_dSN)rr known_attrsr)selfrrrs W/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/sphinx/domains/__init__.py__init__zObjType.__init__8s# &+ %)%5%= N)rrrr rr r r!)__name__ __module__ __qualname____doc__r$r'r(r&rr&s@   aK>>>>>>r(rceZdZUdZdZdZiZded<iZded<iZ ded<gZ d ed <iZ d ed <iZ d ed<iZ ded<ded<dZdGdZdHdZdIdZdJdZdKd!ZdLd#ZdMd'ZdNd*ZdHd+ZdOd.ZdPd8ZdQd:ZdRd<ZdSdTdAZdUdDZdVdEZdFS)WraA 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[str, Any] initial_datadatarenvrr r!c|j}||_i|_i|_i|_i|_t |j|_t |j|_t |j |_ t|j |_ |j |vrQt|jt sJtj|j}|j|d<|x|_||j <n?||j |_|jd|jkrt'd|jz|jD][\}}|j D]0}|j|g|1|j r |j dnd|j|<\|jj|_|jj|_dS)Nversionzdata of %r domain out of daterr/) domaindatar8 _role_cache_directive_cache _role2type _type2roledictr0r1rlistr2name isinstancer6copydeepcopy data_versionr7OSErrorlabelitems setdefaultappendgetobjtypes_for_rolerole_for_objtype)r%r8 domain_datanew_datarBobjrolenames r&r'zDomain.__init__ks14 %(46<>02*,!!233t//$*%% DL)) 9K ' 'd/66 6 6 6}T%677H"&"3HY 19 9DI DI..#DI.DIy#t'888= JKKK*0022 F FID#I F F**8R88??EEEE47I$ECIaLL2DOD ! !!%!4 $ 3r(c|jjj}|jD]>}|jr5|jr.|jd|j}|||d|j?dS)zSet up domain object.-r/N)r8domainsstandard_domainr2rB localnamenote_hyperlink_target)r%stdindexdocnames r&setupz Domain.setupsyh.\ Q QEz Qeo Q!Y5555))'7BPPP Q Qr(rBrobjtyperc||j|<|jr|jd|j|<n d|j|<|jD]0}|j|g|1dS)zAdd an object type.rr/N)r0rr?r>rJrK)r%rBr]roles r&add_object_typezDomain.add_object_types")$ = '$+M!$4DOD ! !$&DOD !M > >D O & &tR 0 0 7 7 = = = = > >r(RoleFunction | Nonecjvr jSjvrdSjd ddfd }|j<|S)zReturn a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. N:r-typrrawtexttextlinenointinlinerroptionsdict[str, Any] | Nonecontent Sequence[str]r -tuple[list[Node], list[nodes.system_message]]c @ j|||||pi|Sr#)r) rdrerfrgrirjrlfullnamerBr%s r& role_adapterz!Domain.role..role_adapters3$4:d#'4'-R r()Nr-)rdrrerrfrrgrhrirrjrkrlrmr rn)r<rrB)r%rBrqrps`` @r&r_z Domain.roles 4# # ##D) ) tz ! !4i(($((.2%'         ".r(type[Directive] | Nonec||jvr |j|S||jvrdS|jd||j|}Gfdd|}||j|<|S)zReturn a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. Nrcc$eZdZdfd ZxZS)*Domain.directive..DirectiveAdapterr list[Node]cR|_tSr#)rBsuperrun)r% __class__rps r&ryz.Domain.directive..DirectiveAdapter.runs$ ww{{}}$r()r rv)r)r*r+ry __classcell__)rzrps@r&DirectiveAdapterrusC % % % % % % % % % % %r(r|)r=r1rB)r%rB BaseDirectiver|rps @r& directivezDomain.directives 4( ( ((. . t & &4i(($((-  % % % % % % %} % % % '7d#r(r[cdS)z?Remove traces of a document in the domain-specific inventories.Nr-)r%r[s r& clear_doczDomain.clear_doc r(docnamesSet[str] otherdatac6d|jd}t|)zMerge in data regarding *docnames* from a different domaindata inventory (coming from a subprocess in parallel builds). z(merge_domaindata must be implemented in z" to be able to do parallel builds!)rzNotImplementedError)r%rrmsgs r&merge_domaindatazDomain.merge_domaindatas/  0t~ 0 0 0 "#&&&r(documentnodes.documentcdS)z7Process a document after it is read by the environment.Nr-)r%r8r[rs r& process_doczDomain.process_doc  r(cdS)z)Do consistency checks (**experimental**).Nr-r%s r&check_consistencyzDomain.check_consistencyrr(pnodercdS)zxProcess a pending xref created in a doc field. For example, attach information about the current scope. Nr-)r%rs r&process_field_xrefzDomain.process_field_xrefrr( fromdocnamebuilderrrdtargetnodecontnoder nodes.reference | NonecdS)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%r8rrrdrrrs r& resolve_xrefzDomain.resolve_xrefs . r(!list[tuple[str, nodes.reference]]ct)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 )r)r%r8rrrrrs r&resolve_any_xrefzDomain.resolve_any_xrefs ,"!r(-Iterable[tuple[str, str, str, str, str, int]]cgS)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-rs r& get_objectszDomain.get_objectss B r(FtypeprimaryboolcP|r|jStd|j|jfzS)z#Return full name for given ObjType.z%s %s)rrrH)r%rrs r& get_type_namezDomain.get_type_name>s,  : zzTZ444r(r str | NonecL|j|jd\}}|S)z,Get type of enumerable nodes (experimental).)NN)r4rLrz)r%renum_node_typers r&get_enumerable_node_typezDomain.get_enumerable_node_typeDs' 155dnlSSr(cdS)z*Return full qualified name for given node.Nr-)r%rs r&get_full_qualified_namezDomain.get_full_qualified_nameIrr(N)r8rr r!)r r!)rBrr]rr r!)rBrr ra)rBrr rr)r[rr r!)rrrr5r r!)r8rr[rrrr r!)rrr r!)r8rrrrrrdrrrrrrr r r)r8rrrrrrrrrrr r r)r r)F)rrrrr r)rrr r)rr r r)r)r*r+r,rBrHr0__annotations__r1rr2r3r4r6rFr'r\r`r_r~rrrrrrrrrrrr-r(r&rr>s, D E')L))))-/J////02E2222!#G####(*****IKKKKK#%L%%%%L4444<QQQQ > > > >4    *    ''''                2""""0!!!!F55555        r(r)'r, __future__rrDtypingrsphinx.domains._indexrr sphinx.localercollections.abcrr r r docutilsr docutils.nodesr rdocutils.parsers.rstrdocutils.parsers.rst.statesrsphinx.addnodesrsphinx.buildersrsphinx.environmentr sphinx.rolesrsphinx.util.typingrr__all__rrr-r(r&rs #""""" 33333333 =7777777777,,,,,,,,......333333,,,,,,''''''333333%%%%%%<<<<<<<< >>>>>>>>0M M M M M M M M M M r(