o $a;<@sdZddlZddlmZmZddlmZmZmZm Z m Z m Z m Z m Z mZmZmZmZddlmZddlmZmZmZddlmZddlmZdd lmZdd lmZdd l m!Z!dd l"m#Z#erldd l$m%Z%ddl&m'Z'GdddZ(Gddde Z)GdddeZ*GdddZ+dS)a' sphinx.domains ~~~~~~~~~~~~~~ Support for domains, which are groupings of description directives and roles describing e.g. constructs of one programming language. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N)ABCabstractmethod) TYPE_CHECKINGAnyCallableDictIterableList NamedTupleOptionalTupleTypeUnioncast)nodes)ElementNodesystem_message)Inliner) pending_xref) SphinxError)_)XRefRole) RoleFunction)Builder)BuildEnvironmentc@s2eZdZdZddiZdedededdfd d ZdS) ObjTypea3 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()`. searchpriolnamerolesattrsreturnNcOs(||_||_|j|_|j|dSN)rr known_attrscopyr!update)selfrr r!r(9/usr/lib/python3/dist-packages/sphinx/domains/__init__.py__init__3s zObjType.__init__)__name__ __module__ __qualname____doc__r$strrr*r(r(r(r)r s rc@sFeZdZUeed<eed<eed<eed<eed<eed<eed<dS) IndexEntrynamesubtypedocnameanchorextra qualifierdescrN)r+r,r-r/__annotations__intr(r(r(r)r0:s  r0c @steZdZUdZdZeed<dZeed<dZeed<dd d Z e dd e ede e e ee efeffd d ZdS)Indexa An Index is the description for a domain-specific index. To add an index to a domain, subclass Index, overriding the three name attributes: * `name` is an identifier used for generating file names. It is also used for a hyperlink target for the index. Therefore, users can refer the index page using ``ref`` role and a string which is combined domain name and ``name`` attribute (ex. ``:ref:`py-modindex```). * `localname` is the section title for the index. * `shortname` is a short name for the index, for use in the relation bar in HTML output. Can be empty to disable entries in the relation bar. and providing a :meth:`generate()` method. Then, add the index class to your domain's `indices` list. Extensions can add indices to existing domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`. .. versionchanged:: 3.0 Index pages can be referred by domain name and index name via :rst:role:`ref` role. Nr1 localname shortnamedomainDomainr"cCs.|jdus |jdurtd|jj||_dS)Nz0Index subclass %s has no valid name or localname)r1r;r __class__r+r=)r'r=r(r(r)r*_s  zIndex.__init__docnamescCt)aGet entries for the index. If ``docnames`` is given, restrict to entries referring to these docnames. The return value is a tuple of ``(content, collapse)``: ``collapse`` A boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries). ``content``: A sequence of ``(letter, entries)`` tuples, where ``letter`` is the "heading" for the given ``entries``, usually the starting letter, and ``entries`` is a sequence of single entries. Each entry is a sequence ``[name, subtype, docname, anchor, extra, qualifier, descr]``. The items in this sequence have the following meaning: ``name`` The name of the index entry to be displayed. ``subtype`` The sub-entry related type. One of: ``0`` A normal entry. ``1`` An entry with sub-entries. ``2`` A sub-entry. ``docname`` *docname* where the entry is located. ``anchor`` Anchor for the entry within ``docname`` ``extra`` Extra info for the entry. ``qualifier`` Qualifier for the description. ``descr`` Description for the entry. Qualifier and description are not rendered for some output formats such as LaTeX. NotImplementedError)r'r@r(r(r)generatees4zIndex.generate)r=r>r"Nr#)r+r,r-r.r1r/r8r;r<r*rrr r r0boolrDr(r(r(r)r:Ds      r:c@s>eZdZUdZdZdZiZeee fe d<iZ eee fe d<iZ eeeeeffe d<gZeeee d<iZeeefe d<iZeeeeeeffe d<iZee d <ee d <d ZdAddZdBddZdede ddfddZdedeefddZ dedeefddZ!deddfddZ"deed eddfd!d"Z#d d ded#e$j%ddfd$d%Z&dBd&d'Z'd(e(ddfd)d*Z)d d d+ed,d-d.ed/ed0e(d1e*dee*fd2d3Z+d d d+ed,d-d/ed0e(d1e*deeee*ffd4d5Z,de-eeeeeee.ffd6d7Z/dCd9e d:e0defd;d<Z1d0edeefd=d>Z2d0e*deefd?d@Z3dS)Dr>a 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. object_types directivesr indicesdangling_warningsenumerable_nodes initial_datadatarenvrr"NcCs&||_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 daterrF)rN _role_cache_directive_cache _role2type _type2roledictrGrHr listrIr1 domaindata isinstancerLr%deepcopy data_versionrMOSErrorlabelitems setdefaultappendgetobjtypes_for_rolerole_for_objtype)r'rNnew_datar1objrolenamer(r(r)r*s.         zDomain.__init__cCs\ddlm}t||jd}|jD]}|jr+|jr+d|j|jf}|||d|jqdS)zSet up domain object.r)StandardDomainstdz%s-%srFN) sphinx.domains.stdrerrN get_domainrIr1r;note_hyperlink_target)r'rerfindexr3r(r(r)setups   z Domain.setupr1objtypecCsP||j|<|jr|jd|j|<nd|j|<|jD] }|j|g|qdS)zAdd an object type.rrFN)rGr rSrRr]r^)r'r1rlroler(r(r)add_object_types   zDomain.add_object_typecsjvr jSjvrdSdjfigfdtdtdtdtdtdtd ttd ttt tt fffd d }|j<|S) zReturn a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. N%s:%styprawtexttextlinenoinlineroptionscontentr"csj||||||Sr#)r )rprqrrrsrtrurvfullnamer1r'r(r) role_adaptersz!Domain.role..role_adapter) rPr r1r/r9rrr r rr)r'r1ryr(rwr)rms"    z Domain.rolecs\||jvr |j|S||jvrdSd|j|f|j|}Gfddd|}||j|<|S)zReturn a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. Nrocs(eZdZdeeffdd ZZS)z*Domain.directive..DirectiveAdapterr"cs|_tSr#)r1superrunr')r?rxr(r)r{s z.Domain.directive..DirectiveAdapter.run)r+r,r-r rr{ __classcell__r(rx)r?r)DirectiveAdapters r)rQrHr1)r'r1 BaseDirectiverr(r~r) directives     zDomain.directiver3cCdS)z?Remove traces of a document in the domain-specific inventories.Nr()r'r3r(r(r) clear_doc$zDomain.clear_docr@ 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!)rCr?)r'r@rr(r(r)merge_domaindata(szDomain.merge_domaindatadocumentcCr)z7Process a document after it is read by the environment.Nr()r'rNr3rr(r(r) process_doc0szDomain.process_doccCr)z)Do consistency checks (**experimental**).Nr(r|r(r(r)check_consistency5rzDomain.check_consistencypnodecCr)zxProcess a pending xref created in a doc field. For example, attach information about the current scope. Nr()r'rr(r(r)process_field_xref9szDomain.process_field_xref fromdocnamebuilderrrptargetnodecontnodecCr)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'rNrrrprrrr(r(r) resolve_xref?zDomain.resolve_xrefcCrA)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 rB)r'rNrrrrrr(r(r)resolve_any_xrefQrzDomain.resolve_any_xrefcCsgS)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(r|r(r(r) get_objectscs!zDomain.get_objectsFtypeprimarycCs|r|jStd|j|jfS)z#Return full name for given ObjType.z%s %s)rrr[)r'rrr(r(r) get_type_nameszDomain.get_type_namecCs|j|jd\}}|S)z,Get type of enumerable nodes (experimental).)NN)rKr_r?)r'renum_node_typerr(r(r)get_enumerable_node_typeszDomain.get_enumerable_node_typecCr)z*Return full qualified name for given node.Nr()r'rr(r(r)get_full_qualified_namerzDomain.get_full_qualified_name)rNrr"N)r"N)F)4r+r,r-r.r1r[rGrr/rr8rHrr rrrrIr r r:rJrKrr rrLrYr*rkrnr rmrrrrrrrrrrrrrr9rrErrrr(r(r(r)r>sf           "#r>),r.r%abcrrtypingrrrrrr r r r r rrdocutilsrdocutils.nodesrrrdocutils.parsers.rst.statesrsphinx.addnodesr sphinx.errorsr sphinx.localer sphinx.rolesrsphinx.util.typingrsphinx.buildersrsphinx.environmentrrr0r:r>r(r(r(r)s& 8          X