o

�$�a;<�@s
dZd
dl
Z
d
dlmZmZ
d
dlmZmZmZm	Z	m
Z
mZmZm
Z
mZmZmZmZ
d
dlmZ
d
dlmZmZmZ
d
dlmZ
d
dlmZ
d
d	lmZ
d
d
lmZ
d
dl m!Z!
d
dl"m#Z#
erld
d
l$m%Z%
d
dl&m'Z'
Gdd�d�Z(Gdd�de�Z)Gdd�de�Z*Gdd�d�Z+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)�ABC�abstractmethod)�
TYPE_CHECKING�Any�Callable�Dict�Iterable�List�
NamedTuple�Optional�Tuple�Type�Union�cast)
�nodes)�Element�Node�system_message)
�Inliner)
�pending_xref)
�SphinxError)
�
_)
�XRefRole)
�RoleFunction)
�Builder)
�BuildEnvironmentc@s2eZ
dZd
Zddi
Zdedededdfd	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()`.
    �
searchprio�
�lname�roles�attrs�returnNcOs(|
|_||_
|j��|_|j�|�

dS�
N)rr �known_attrs�copyr!�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@sFeZ
dZUeed
<eed<eed<eed<eed<eed<eed<dS)	�
IndexEntry�name�subtype�docname�anchor�extra�	qualifier�descrN)r+r,r-r/�__annotations__�intr(r(r(r)r0:s







r0c@steZ
dZUd
ZdZeed<dZeed<dZeed<dd	d
�Z	e
ddeede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�	shortname�domain�Domainr"cCs.|jdus
|j
durtd
|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__�docnamesc
C�t�
)
a�Get 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	r0�boolrDr(r(r(r)r:Ds






�r:c@s>eZ
dZUd
ZdZdZiZeee	fe
d<iZeeefe
d<iZ
eeeeeffe
d<gZeeee
d<iZeeefe
d<iZeeeeeeffe
d<iZee
d	<ee
d
<dZdAdd�ZdBdd�Zdede	ddfdd�Zdedeefdd�Z dedeefdd�Z!deddfdd�Z"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*fd2d3�Z+dd
d+ed,d-d/ed0e(d1e*deeee*ffd4d5�Z,de-eeeeeee.ffd6d7�Z/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 �indices�dangling_warnings�enumerable_nodes�initial_data�datar
�envrr"NcCs&
|
|_i|_
i|_i|_i|_t|j�
|_t|j�
|_t|j�
|_t	|j
�
|_
|j|
jv
rJt
|jt�s5J�
t�|j�
}|j|d
<||_|
j|j<n|
j|j|_|jd
|jkr`td|j�
�
|j��D]!\}}|jD]}|j�|g��|�

ql|jr�|jdn
d|j|<qe|jj|_|jj|_dS)N�versionzdata of %r domain out of dater
rF)rN�_role_cache�_directive_cache�
_role2type�
_type2role�dictrGrHr �listrIr1�
domaindata�
isinstancerLr%�deepcopy�data_versionrM�OSError�label�items�
setdefault�append�get�objtypes_for_role�role_for_objtype)r'rN�new_datar1�obj�rolenamer(r(r)r*�s.






















zDomain.__init__c
Cs\d
dlm
}

t|
|j�d�
�}|jD]}|jr+|jr+d|j|jf}|�||d|j�
qdS)zSet up domain object.r
)
�StandardDomain�stdz%s-%srFN)	�sphinx.domains.stdrerrN�
get_domainrIr1r;�note_hyperlink_target)r'rerf�indexr3r(r(r)�setup�s




��zDomain.setupr1�objtypecCsP||j|
<|j
r|j
d
|j|
<nd|j|
<|j
D]}|j�|g��|
�

qdS)zAdd an object type.r
rFN)rGr rSrRr]r^)r'r1rl�roler(r(r)�add_object_type�s





�zDomain.add_object_typecs��
�jvr
�j�
S�
�j
v
rd
Sd�j�
f�igfdtdtdtdtdtdtd	ttd
ttt	tt
ff��
�fdd�
}|�j�
<|S)
z�Return a role adapter function that always gives the registered
        role its full name ('domain:name') as the first argument.
        N�%s:%s�typ�rawtext�text�lineno�inliner�options�contentr"cs�j�
�|
|||||�Sr#)
r )rprqrrrsrtrurv��fullnamer1r'r(r)�role_adapter
s
�z!Domain.role.<locals>.role_adapter)rPr r1r/r9rrr	rrr)r'r1ryr(rwr)rm�s"






�
�
�
��

zDomain.rolecs\|
|jvr
|j|
S|
|j
v
rd
Sd|j|
f�|j
|
}G�f
dd�d|�}||j|
<|S)z�Return a directive adapter class that always gives the registered
        directive its full name ('domain:name') as ``self.name``.
        Nrocs(eZ
dZd
eef��
fdd�Z�ZS)z*Domain.directive.<locals>.DirectiveAdapterr"c

s�
|_t
���Sr#)r1�super�run�
r')r?rxr(r)r{
s


z.Domain.directive.<locals>.DirectiveAdapter.run)r+r,r-r	rr{�
__classcell__r(�
rx)
r?r)�DirectiveAdapter
s 
r)rQrHr1)r'r1�
BaseDirectiverr(r~r)�	directive
s










zDomain.directiver3c
C�d
S)z?Remove traces of a document in the domain-specific inventories.Nr()r'r3r(r(r)�	clear_doc$
�zDomain.clear_docr@�	otherdatacCstd
|j
�
�
)z�Merge 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@r�r(r(r)�merge_domaindata(
s�zDomain.merge_domaindata�documentc
Cr�)z7Process a document after it is read by the environment.Nr()r'rNr3r�r(r(r)�process_doc0
szDomain.process_docc


Cr�)z)Do consistency checks (**experimental**).Nr(r|r(r(r)�check_consistency5
r�zDomain.check_consistency�pnodec
Cr�)zxProcess a pending xref created in a doc field.
        For example, attach information about the current scope.
        Nr()r'r�r(r(r)�process_field_xref9
szDomain.process_field_xref�fromdocname�builderrrp�target�node�contnodec
Cr�)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'rNr�r�rpr�r�r�r(r(r)�resolve_xref?
�zDomain.resolve_xrefc
CrA)
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'rNr�r�r�r�r�r(r(r)�resolve_any_xrefQ
r�zDomain.resolve_any_xrefc


CsgS)
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_objectsc
s!zDomain.get_objectsF�type�primarycCs|r|
jSt
d
�
|j|
jfS)z#Return full name for given ObjType.z%s %s)rrr[)r'r�r�r(r(r)�
get_type_name�
s

zDomain.get_type_namecCs|j�
|
jd
�\}}|S)z,Get type of enumerable nodes (experimental).)NN)rKr_r?)r'r��enum_node_typerr(r(r)�get_enumerable_node_type�
s
zDomain.get_enumerable_node_typec
Cr�)z*Return full qualified name for given node.Nr()r'r�r(r(r)�get_full_qualified_name�
r�zDomain.get_full_qualified_name)rNrr"N)r"N)
F)4r+r,r-r.r1r[rGrr/rr8rHrr rrrrIr	r
r:rJrKrrrrLrYr*rkrnrrmr�r�r�rr�r�r�rr�rr�r�rr9r�rEr�r�r�r(r(r(r)r>�sf

 



�

�

�
�
�
�
�
�
�
�
�"#r>),r.r%�abcrr�typingrrrrrr	r
rrr
rr�docutilsr�docutils.nodesrrr�docutils.parsers.rst.statesr�sphinx.addnodesr�
sphinx.errorsr�
sphinx.localer�sphinx.rolesr�sphinx.util.typingr�sphinx.buildersr�sphinx.environmentrrr0r:r>r(r(r(r)�<module>
s&
8









X