U
    \Sh;                     @  s.  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mZ ddlmZ ddlmZ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  erddl!m"Z" ddl#m$Z$ ddl%m&Z& G dd dZ'G dd deZ(G dd deZ)e
egee* f Z+G dd dZ,dS )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Iterable
NamedTupleOptionalcast)nodes)ElementNodesystem_message)Inliner)pending_xref)SphinxError)_)XRefRole)RoleFunction)	Directive)Builder)BuildEnvironmentc                   @  s,   e Zd ZdZddiZddddddd	Zd
S )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()`.
    Z
searchprio   strr   None)lnamerolesattrsreturnc                 O  s(   || _ || _| j | _| j| d S N)r   r   known_attrscopyr   update)selfr   r   r    r&   J/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/domains/__init__.py__init__1   s    zObjType.__init__N)__name__
__module____qualname____doc__r"   r(   r&   r&   r&   r'   r      s
    r   c                   @  sF   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	< d
S )
IndexEntryr   nameintsubtypedocnameanchorextraZ	qualifierdescrN)r)   r*   r+   __annotations__r&   r&   r&   r'   r-   8   s   
r-   c                   @  sT   e Zd ZU dZded< ded< dZded< dd	d
ddZeddddddZdS )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   r.   	localnameN
str | None	shortnameDomainr   )domainr    c                 C  s.   | j d ks| jd kr$td| jj || _d S )Nz0Index subclass %s has no valid name or localname)r.   r7   r   	__class__r)   r;   )r%   r;   r&   r&   r'   r(   ]   s
    zIndex.__init__zIterable[str] | Nonez/tuple[list[tuple[str, list[IndexEntry]]], bool])docnamesr    c                 C  s   t dS )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.
        NNotImplementedError)r%   r=   r&   r&   r'   generatec   s    4zIndex.generate)N)	r)   r*   r+   r,   r5   r9   r(   r   r@   r&   r&   r&   r'   r6   B   s   
r6   c                	   @  s  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dddZddddZddddddZdd d!d"d#Zdd$d!d%d&Zddd'd(d)Zd*ddd+d,d-Zddd.dd/d0d1Zddd2d3Zd4dd5d6d7Zddd8ddd4d9d:d;d<d=Zddd8dd4d9d>d?d@dAZdBddCdDZdRddFddGdHdIZdJdKdLdMdNZd9dKdLdOdPZdQS )Sr:   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   r   r   )envr    c                 C  s(  || _ i | _i | _i | _i | _t| j| _t| j| _t| j| _t	| j
| _
| j|jkrt| jtsjtt| j}| j|d< | | _|j| j< n,|j| j | _| jd | jkrtd| j | j D ]D\}}|jD ]}| j|g | q|jr|jd nd| j|< q| jj| _| jj| _d S )Nversionzdata of %r domain out of dater   rA   )rJ   _role_cache_directive_cache
_role2type
_type2rolerG   rB   rC   r   listrD   r.   Z
domaindata
isinstancerH   AssertionErrorr#   deepcopydata_versionrI   OSErrorlabelitems
setdefaultappendgetZobjtypes_for_roleZrole_for_objtype)r%   rJ   Znew_datar.   objZrolenamer&   r&   r'   r(      s.    


zDomain.__init__r    c                 C  s^   ddl m} t|| jd}| jD ]4}|jr$|jr$| j d|j }|||d|j q$dS )zSet up domain object.r   )StandardDomainstd-rA   N)	Zsphinx.domains.stdr]   r   rJ   Z
get_domainrD   r.   r7   Znote_hyperlink_target)r%   r]   r^   indexr1   r&   r&   r'   setup   s    
zDomain.setupr   r   )r.   objtyper    c                 C  sP   || j |< |jr"|jd | j|< n
d| j|< |jD ]}| j|g | q2dS )zAdd an object type.r   rA   N)rB   r   rO   rN   rX   rY   )r%   r.   rb   roler&   r&   r'   add_object_type   s    


zDomain.add_object_typezRoleFunction | None)r.   r    c              
     sj   j krj  S jkr"dS j d  i g fddddddddd	 fd
d}|j < |S )zReturn a role adapter function that always gives the registered
        role its full name ('domain:name') as the first argument.
        N:r   r/   r   rG   	list[str]z'tuple[list[Node], list[system_message]])typrawtexttextlinenoinlineroptionscontentr    c                   s   j   ||||||S r!   )r   )rg   rh   ri   rj   rk   rl   rm   fullnamer.   r%   r&   r'   role_adapter  s
      z!Domain.role.<locals>.role_adapter)rL   r   r.   )r%   r.   rp   r&   rn   r'   rc      s    


 &
zDomain.rolezCallable | Nonec                   s^   || j kr| j | S || jkr"dS | j d|  | j| }G  fddd|}|| j |< |S )zReturn a directive adapter class that always gives the registered
        directive its full name ('domain:name') as ``self.name``.
        Nre   c                      s$   e Zd Zdd fddZ  ZS )z*Domain.directive.<locals>.DirectiveAdapterz
list[Node]r\   c                   s   | _ t  S r!   )r.   superrunr%   )r<   ro   r&   r'   rr     s    z.Domain.directive.<locals>.DirectiveAdapter.run)r)   r*   r+   rr   __classcell__r&   ro   )r<   r'   DirectiveAdapter  s   rv   )rM   rC   r.   )r%   r.   ZBaseDirectiverv   r&   ru   r'   	directive  s    




zDomain.directive)r1   r    c                 C  s   dS )z?Remove traces of a document in the domain-specific inventories.Nr&   )r%   r1   r&   r&   r'   	clear_doc$  s    zDomain.clear_docrf   )r=   	otherdatar    c                 C  s   t d| j dS )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!N)r?   r<   )r%   r=   ry   r&   r&   r'   merge_domaindata(  s    zDomain.merge_domaindataznodes.document)rJ   r1   documentr    c                 C  s   dS )z7Process a document after it is read by the environment.Nr&   )r%   rJ   r1   r{   r&   r&   r'   process_doc0  s    zDomain.process_docc                 C  s   dS )z)Do consistency checks (**experimental**).Nr&   rs   r&   r&   r'   check_consistency5  s    zDomain.check_consistencyr   )pnoder    c                 C  s   dS )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  s    zDomain.process_field_xrefr   r   zElement | None)rJ   fromdocnamebuilderrg   targetnodecontnoder    c                 C  s   dS )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.
        Nr&   )r%   rJ   r   r   rg   r   r   r   r&   r&   r'   resolve_xref?  s    zDomain.resolve_xrefzlist[tuple[str, Element]])rJ   r   r   r   r   r   r    c                 C  s   t dS )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
        Nr>   )r%   rJ   r   r   r   r   r   r&   r&   r'   resolve_any_xrefQ  s    zDomain.resolve_any_xrefz-Iterable[tuple[str, str, str, str, str, int]]c                 C  s   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.
        r&   rs   r&   r&   r'   get_objectsc  s    !zDomain.get_objectsFbool)typeprimaryr    c                 C  s   |r
|j S td| j|j f S )z#Return full name for given ObjType.z%s %s)r   r   rV   )r%   r   r   r&   r&   r'   get_type_name  s    zDomain.get_type_namer   r8   )r   r    c                 C  s   | j |jd\}}|S )z,Get type of enumerable nodes (experimental).)NN)rF   rZ   r<   )r%   r   Zenum_node_typer   r&   r&   r'   get_enumerable_node_type  s    zDomain.get_enumerable_node_typec                 C  s   dS )z*Return full qualified name for given node.Nr&   )r%   r   r&   r&   r'   get_full_qualified_name  s    zDomain.get_full_qualified_nameN)F)r)   r*   r+   r,   r.   rV   rB   r5   rC   r   rD   rE   rF   rH   rT   r(   ra   rd   rc   rw   rx   rz   r|   r}   r   r   r   r   r   r   r   r&   r&   r&   r'   r:      s8   
#r:   )-r,   
__future__r   r#   abcr   r   typingr   r   r   r   r	   r
   r   Zdocutilsr   Zdocutils.nodesr   r   r   Zdocutils.parsers.rst.statesr   Zsphinx.addnodesr   Zsphinx.errorsr   Zsphinx.localer   Zsphinx.rolesr   Zsphinx.util.typingr   Zdocutils.parsers.rstr   Zsphinx.buildersr   Zsphinx.environmentr   r   r-   r6   r   ZTitleGetterr:   r&   r&   r&   r'   <module>   s*   $
X