
    Fe<                    V   d Z ddlmZ ddlZddlmZmZ ddlmZm	Z	m
Z
mZmZmZ ddlmZmZmZ ddlmZ ddlmZ er8dd	lmZmZ dd
lmZ ddlmZ ddlmZ ddlm Z  ddl!m"Z" ddl#m$Z$ ddl%m&Z& ddl'm(Z(  G d d      Z) G d de      Z* G d de      Z+e
egee,   f   Z- G d d      Z.y)zSupport for domains.

Domains are groupings of description directives
and roles describing e.g. constructs of one programming language.
    )annotationsN)ABCabstractmethod)TYPE_CHECKINGAnyCallable
NamedTupleOptionalcast)ElementNodesystem_message)SphinxError)_)IterableSequence)nodes)	Directive)Inliner)pending_xref)Builder)BuildEnvironment)XRefRole)RoleFunctionc                       e Zd ZdZddiZddZy)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   c                    || _         || _        | j                  j                         | _        | j                  j                  |       y N)lnamerolesknown_attrscopyattrsupdate)selfr!   r"   r%   s       9/usr/lib/python3/dist-packages/sphinx/domains/__init__.py__init__zObjType.__init__3   s8    
!
++002


%     N)r!   strr"   r   r%   r   returnNone)__name__
__module____qualname____doc__r#   r)    r*   r(   r   r       s     	aK!r*   r   c                  T    e Zd ZU ded<   ded<   ded<   ded<   ded<   ded<   ded	<   y
)
IndexEntryr+   nameintsubtypedocnameanchorextra	qualifierdescrN)r.   r/   r0   __annotations__r2   r*   r(   r4   r4   :   s%    
ILLKJNJr*   r4   c                  R    e Zd ZU dZded<   ded<   dZded<   d
dZed	 dd	       Zy)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.
    r+   r5   	localnameN
str | None	shortnamec                    | j                   | j                  "t        d| j                  j                  z        || _        y )Nz0Index subclass %s has no valid name or localname)r5   r@   r   	__class__r.   domain)r'   rE   s     r(   r)   zIndex.__init___   s>    99 6P $ 7 78 9 9r*   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'   docnamess     r(   generatezIndex.generatee   s    h "!r*   )rE   Domainr,   r-   r    )rI   zIterable[str] | Noner,   z/tuple[list[tuple[str, list[IndexEntry]]], bool])	r.   r/   r0   r1   r=   rB   r)   r   rJ   r2   r*   r(   r?   r?   D   s>    , IN Iz  3"E3" 3"r*   r?   c                  8   e Zd ZU dZdZdZi Zded<   i Zded<   i Z	ded<   g Z
d	ed
<   i Zded<   i Zded<   i Zded<   ded<   dZd$dZd%dZd&dZd'dZd(dZd)dZd*dZ	 	 	 	 d+dZd%dZd,dZ	 	 	 	 	 	 	 	 	 	 d-dZ	 	 	 	 	 	 	 	 d.dZd/dZd0d1d Zd2d!Zd3d"Zy#)4rK   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.
     zdict[str, ObjType]object_typeszdict[str, type[Directive]]
directivesz"dict[str, RoleFunction | XRefRole]r"   zlist[type[Index]]indiceszdict[str, str]dangling_warningsz0dict[type[Node], tuple[str, TitleGetter | None]]enumerable_nodesdictinitial_datadatar   c                @   || _         i | _        i | _        i | _        i | _        t        | j                        | _        t        | j                        | _        t        | j                        | _        t        | j                        | _
        | j                  |j                  vrkt        | j                  t
              sJ t        j                   | j                        }| j"                  |d<   |x| _        |j                  | j                  <   nR|j                  | j                     | _        | j$                  d   | j"                  k7  rt'        d| j(                  z        | j                  j+                         D ]k  \  }}|j                  D ]-  }| j                  j-                  |g       j/                  |       / |j                  r|j                  d   nd| j                  |<   m | j                  j0                  | _        | j                  j0                  | _        y )Nversionzdata of %r domain out of dater   rM   )env_role_cache_directive_cache
_role2type
_type2rolerS   rN   rO   r"   listrP   r5   
domaindata
isinstancerT   r$   deepcopydata_versionrU   OSErrorlabelitems
setdefaultappendgetobjtypes_for_rolerole_for_objtype)r'   rX   new_datar5   objrolenames         r(   r)   zDomain.__init__   s   %(025702*, !!2!23t/$**%
DLL)99CNN*d//666}}T%6%67H"&"3"3HY4<<DItyy1tyy1DIyy#t'8'88=

JKK**002 	FID#II F**8R8??EF47IICIIaL2DOOD!	F "&!4!4 $ 3 3r*   c                "   ddl m} t        || j                  j	                  d            }| j
                  D ]U  }|j                  s|j                  s| j                   d|j                   }|j                  ||d|j                         W y)zSet up domain object.r   )StandardDomainstd-rM   N)	sphinx.domains.stdrn   r   rX   
get_domainrP   r5   r@   note_hyperlink_target)r'   rn   ro   indexr8   s        r(   setupzDomain.setup   st    5 >488#6#6u#=>\\ 	QEzzeoo!YYKq5))'7BP	Qr*   c                
   || j                   |<   |j                  r|j                  d   | j                  |<   nd| j                  |<   |j                  D ]-  }| j                  j	                  |g       j                  |       / y)zAdd an object type.r   rM   N)rN   r"   r\   r[   re   rf   )r'   r5   objtyperoles       r(   add_object_typezDomain.add_object_type   sp    ")$==$+MM!$4DOOD!$&DOOD!MM 	>DOO&&tR077=	>r*   c                      j                   v r j                      S  j                  vry j                   d 	 	 d	 	 	 	 	 	 	 d fd}| j                   <   |S )zReturn a role adapter function that always gives the registered
        role its full name ('domain:name') as the first argument.
        N:c           	     B     	j                      |||||xs i |      S r    )r"   )
typrawtexttextlinenoinlineroptionscontentfullnamer5   r'   s
          r(   role_adapterz!Domain.role.<locals>.role_adapter
  s2     $4::d#HgtV$+W]GE Er*   )Nr2   )r}   r+   r~   r+   r   r+   r   r6   r   r   r   zdict | Noner   zSequence[str]r,   z'tuple[list[Node], list[system_message]])rY   r"   r5   )r'   r5   r   r   s   `` @r(   rx   zDomain.role   s     4#####D))tzz!ii[$( CG24	E")	E4?	E"/	E F	E ".r*   c                    || j                   v r| j                   |   S || j                  vry| j                   d| | j                  |   } G fdd|      }|| j                   |<   |S )zReturn a directive adapter class that always gives the registered
        directive its full name ('domain:name') as ``self.name``.
        Nr{   c                  $     e Zd Zd fdZ xZS )*Domain.directive.<locals>.DirectiveAdapterc                .    | _         t        | 	         S r    )r5   superrun)r'   rD   r   s    r(   r   z.Domain.directive.<locals>.DirectiveAdapter.run  s    $	w{}$r*   )r,   z
list[Node])r.   r/   r0   r   __classcell__)rD   r   s   @r(   DirectiveAdapterr     s    % %r*   r   )rZ   rO   r5   )r'   r5   BaseDirectiver   r   s       @r(   	directivezDomain.directive  sy     4(((((..t&ii[$(-	%} 	% '7d#r*   c                     y)z?Remove traces of a document in the domain-specific inventories.Nr2   )r'   r8   s     r(   	clear_doczDomain.clear_doc'      r*   c                2    t        d| j                  z        )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!)rH   rD   )r'   rI   	otherdatas      r(   merge_domaindatazDomain.merge_domaindata+  s#     " #F"&..#1 2 	2r*   c                     y)z7Process a document after it is read by the environment.Nr2   )r'   rX   r8   documents       r(   process_doczDomain.process_doc3  s     	r*   c                     y)z)Do consistency checks (**experimental**).Nr2   r'   s    r(   check_consistencyzDomain.check_consistency8  r   r*   c                     y)zxProcess a pending xref created in a doc field.
        For example, attach information about the current scope.
        Nr2   )r'   pnodes     r(   process_field_xrefzDomain.process_field_xref<  s     	r*   c                     y)aL  Resolve 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.
        Nr2   )r'   rX   fromdocnamebuilderr}   targetnodecontnodes           r(   resolve_xrefzDomain.resolve_xrefB  s      	r*   c                    t         )a9  Resolve 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
        rG   )r'   rX   r   r   r   r   r   s          r(   resolve_any_xrefzDomain.resolve_any_xrefT  s
      "!r*   c                    g S )au  Return 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.
        r2   r   s    r(   get_objectszDomain.get_objectsf  s
    B 	r*   c                f    |r|j                   S t        d      | j                  |j                   fz  S )z#Return full name for given ObjType.z%s %s)r!   r   rc   )r'   typeprimarys      r(   get_type_namezDomain.get_type_name  s+    ::zTZZ444r*   c                X    | j                   j                  |j                  d      \  }}|S )z,Get type of enumerable nodes (experimental).)NN)rR   rg   rD   )r'   r   enum_node_typer   s       r(   get_enumerable_node_typezDomain.get_enumerable_node_type  s)     1155dnnlSr*   c                     y)z*Return full qualified name for given node.Nr2   )r'   r   s     r(   get_full_qualified_namezDomain.get_full_qualified_name  r   r*   N)rX   r   r,   r-   )r,   r-   )r5   r+   rw   r   r,   r-   )r5   r+   r,   zRoleFunction | None)r5   r+   r,   zCallable | None)r8   r+   r,   r-   )rI   z	list[str]r   rS   r,   r-   )rX   r   r8   r+   r   znodes.documentr,   r-   )r   r   r,   r-   )rX   r   r   r+   r   r   r}   r+   r   r+   r   r   r   r   r,   zElement | None)rX   r   r   r+   r   r   r   r+   r   r   r   r   r,   zlist[tuple[str, Element]])r,   z-Iterable[tuple[str, str, str, str, str, int]])F)r   r   r   boolr,   r+   )r   r   r,   rA   )r   r   r,   rA   )r.   r/   r0   r1   r5   rc   rN   r=   rO   r"   rP   rQ   rR   rT   ra   r)   ru   ry   rx   r   r   r   r   r   r   r   r   r   r   r   r   r2   r*   r(   rK   rK      s   . DE')L$)-/J*/02E-2!#G#(*~*IKFKL$
JL4:	Q	>& (2,15
'*2>JQ($"!$",8"DK"7"$!F5
r*   rK   )/r1   
__future__r   r$   abcr   r   typingr   r   r   r	   r
   r   docutils.nodesr   r   r   sphinx.errorsr   sphinx.localer   collections.abcr   r   docutilsr   docutils.parsers.rstr   docutils.parsers.rst.statesr   sphinx.addnodesr   sphinx.buildersr   sphinx.environmentr   sphinx.rolesr   sphinx.util.typingr   r   r4   r?   r+   TitleGetterrK   r2   r*   r(   <module>r      s    #  # K K 8 8 % 2.3,'3%/! !4 U"C U"p vx},-w wr*   