
    O&i;                     J   d 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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rddl$m%Z% ddl&m'Z'  G d d          Z( G d de          Z) G d de          Z* G d d          Z+dS )zSupport for domains.

Domains are groupings of description directives
and roles describing e.g. constructs of one programming language.
    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                   2    e Zd ZdZddiZdedededdf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()`.
    
searchprio   lnamerolesattrsreturnNc                     || _         || _        | j                                        | _        | j                            |           d S N)r!   r"   known_attrscopyr#   update)selfr!   r"   r#   s       d/home/geonatureadmin/si_en_reseau/tutos/venv/lib/python3.11/site-packages/sphinx/domains/__init__.py__init__zObjType.__init__.   sB    
!
+0022

%         )__name__
__module____qualname____doc__r'   strr   r,    r-   r+   r   r      s\          	aK!c !3 ! ! ! ! ! ! ! !r-   r   c                   V    e Zd ZU eed<   eed<   eed<   eed<   eed<   eed<   eed<   dS )	
IndexEntrynamesubtypedocnameanchorextra	qualifierdescrN)r.   r/   r0   r2   __annotations__intr3   r-   r+   r5   r5   5   sO         
IIILLLLLLKKKJJJNNNJJJJJr-   r5   c                       e Zd ZU dZdZeed<   dZeed<   dZeed<   dd	Z	e
dd
ee         deeeeee         f                  ef         f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.
    Nr6   	localname	shortnamedomainDomainr$   c                 h    | j         | j        t          d| j        j        z            || _        d S )Nz0Index subclass %s has no valid name or localname)r6   rA   r   	__class__r.   rC   )r*   rC   s     r+   r,   zIndex.__init__Z   s>    9 6P $ 78 9 9 9r-   docnamesc                     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*   rG   s     r+   generatezIndex.generate`   s    h "!r-   )rC   rD   r$   Nr&   )r.   r/   r0   r1   r6   r2   r=   rA   rB   r,   r   r	   r   r
   r5   boolrK   r3   r-   r+   r@   r@   ?   s          , D#IsIs    3" 3"# 3"DsD,<'<!=>DE3" 3" 3" ^3" 3" 3"r-   r@   c                      e Zd ZU dZdZdZi Zeee	f         e
d<   i Zeeef         e
d<   i Zeeeeef         f         e
d<   g Zeee                  e
d<   i Zeeef         e
d<   i Zeee         eeef         f         e
d<   i Zee
d	<   ee
d
<   dZd1dZd2dZdede	ddfdZdedee         fdZ dedee         fdZ!deddfdZ"dee         deddfdZ#dddede$j%        ddfdZ&d2dZ'de(ddfd Z)ddd!ed"d#d$ed%ed&e(d'e*dee*         fd(Z+ddd!ed"d#d%ed&e(d'e*deeee*f                  fd)Z,de-eeeeeee.f                  fd*Z/d3d,e	d-e0defd.Z1d&edee         fd/Z2d&e*dee         fd0Z3dS )4rD   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   envr   r$   Nc                    || _         i | _        i | _        i | _        i | _        t          | j                  | _        t          | j                  | _        t          | j                  | _        t          | j
                  | _
        | j        |j        vrVt          | j        t
                    sJ t          j        | j                  }| j        |d<   |x| _        |j        | j        <   nD|j        | j                 | _        | j        d         | j        k    rt'          d| j        z            | j                                        D ][\  }}|j        D ]0}| j                            |g                               |           1|j        r|j        d         nd| j        |<   \| j        j        | _        | j        j        | _        d S )Nversionzdata of %r domain out of dater   rN   )rV   _role_cache_directive_cache
_role2type
_type2roledictrO   rP   r"   listrQ   r6   
domaindata
isinstancerT   r(   deepcopydata_versionrU   OSErrorlabelitems
setdefaultappendgetobjtypes_for_rolerole_for_objtype)r*   rV   new_datar6   objrolenames         r+   r,   zDomain.__init__   s   %(025702*, !!233t//$*%%
DL))9CN**d/66666}T%677H"&"3HY4<<DIty11ty1DIy#t'888=
JKKK*0022 	F 	FID#I F F**8R88??EEEE47I$ECIaLL2DOD!!=A_=P6:o6Ir-   c                     ddl m} t          || j                            d                    }| j        D ]>}|j        r5|j        r.| j        d|j        }|                    ||d|j                   ?dS )zSet up domain object.r   )StandardDomainstd-rN   N)	sphinx.domains.stdro   r   rV   
get_domainrQ   r6   rA   note_hyperlink_target)r*   ro   rp   indexr8   s        r+   setupzDomain.setup   s    555555 >48#6#6u#=#=>>\ 	Q 	QEz Qeo Q%)YYY

;))'7BPPP	Q 	Qr-   r6   objtypec                     || j         |<   |j        r|j        d         | j        |<   n
d| j        |<   |j        D ]0}| j                            |g                               |           1dS )zAdd an object type.r   rN   N)rO   r"   r\   r[   rf   rg   )r*   r6   rw   roles       r+   add_object_typezDomain.add_object_type   s    ")$= 	'$+M!$4DOD!!$&DOD!M 	> 	>DO&&tR0077====	> 	>r-   c                 f     j         v r j                  S  j        vrdS  j        di g fdt          dt          dt          dt          dt
          dt          d	t          t                   d
t          t          t                   t          t                   f         f 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:typrawtexttextlinenoinlineroptionscontentr$   c           	      <     	j                  ||||||          S r&   )r"   )
r}   r~   r   r   r   r   r   fullnamer6   r*   s
          r+   role_adapterz!Domain.role.<locals>.role_adapter  s/     $4:d#HgtV$+Wg? ? ?r-   )rY   r"   r6   r2   r>   r   r   r
   r   r   r   )r*   r6   r   r   s   `` @r+   ry   zDomain.role   s     4####D))tz!!4"iii. <>TV	? 	?c 	?C 	?s 	?C 	?")	?48	?HLS		?#DJ^0D$DE	? 	? 	? 	? 	? 	? 	? 	?
 ".r-   c                     || j         v r| j         |         S || j        vrdS | 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                   4     e Zd Zdee         f fdZ xZS )*Domain.directive.<locals>.DirectiveAdapterr$   c                 R    | _         t                                                      S r&   )r6   superrun)r*   rF   r   s    r+   r   z.Domain.directive.<locals>.DirectiveAdapter.run  s    $	ww{{}}$r-   )r.   r/   r0   r
   r   r   __classcell__)rF   r   s   @r+   DirectiveAdapterr     sN        %T$Z % % % % % % % % % % %r-   r   )rZ   rP   r6   )r*   r6   BaseDirectiver   r   s       @r+   	directivezDomain.directive  s     4((((..t&&4"iii.-	% 	% 	% 	% 	% 	% 	%} 	% 	% 	% '7d#r-   r8   c                     dS )z?Remove traces of a document in the domain-specific inventories.Nr3   )r*   r8   s     r+   	clear_doczDomain.clear_doc      r-   rG   	otherdatac                 0    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!)rJ   rF   )r*   rG   r   s      r+   merge_domaindatazDomain.merge_domaindata#  s&     " #F"&.#1 2 2 	2r-   documentc                     dS )z7Process a document after it is read by the environment.Nr3   )r*   rV   r8   r   s       r+   process_doczDomain.process_doc+  s	     	r-   c                     dS )z)Do consistency checks (**experimental**).Nr3   r*   s    r+   check_consistencyzDomain.check_consistency0  r   r-   pnodec                     dS )zxProcess a pending xref created in a doc field.
        For example, attach information about the current scope.
        Nr3   )r*   r   s     r+   process_field_xrefzDomain.process_field_xref4  s	     	r-   fromdocnamebuilderr   r}   targetnodecontnodec                     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.
        Nr3   )r*   rV   r   r   r}   r   r   r   s           r+   resolve_xrefzDomain.resolve_xref:  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
        rI   )r*   rV   r   r   r   r   r   s          r+   resolve_any_xrefzDomain.resolve_any_xrefL  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.
        r3   r   s    r+   get_objectszDomain.get_objects^  s
    B 	r-   Ftypeprimaryc                 P    |r|j         S t          d          | j        |j         fz  S )z#Return full name for given ObjType.z%s %s)r!   r   rd   )r*   r   r   s      r+   get_type_namezDomain.get_type_name  s,     	:zzTZ444r-   c                 L    | j                             |j        d          \  }}|S )z,Get type of enumerable nodes (experimental).)NN)rS   rh   rF   )r*   r   enum_node_typer   s       r+   get_enumerable_node_typezDomain.get_enumerable_node_type  s'     155dnlSSr-   c                     dS )z*Return full qualified name for given node.Nr3   )r*   r   s     r+   get_full_qualified_namezDomain.get_full_qualified_name  s    tr-   )rV   r   r$   N)r$   N)F)4r.   r/   r0   r1   r6   rd   rO   r   r2   r   r=   rP   r   r"   r   r   r   rQ   r
   r   r@   rR   rS   r   r   r   rT   rb   r,   rv   rz   r   ry   r   r   r   r   r   r   r   r   r   r   r   r   r	   r>   r   rL   r   r   r   r3   r-   r+   rD   rD      s         . DE')L$sG|$)))!#JS#X###68E4U<1223888!#GT$u+###(*tCH~***?Ad4:uS(]';;<AAA L$
JJJLJ J J J:	Q 	Q 	Q 	Q	>C 	>' 	>d 	> 	> 	> 	> ,!7    $ c  hx&8        (     2c 2t 2 2 2 2 21 C #n15   
         2  y '*2>JQ"7+   $"$6 "S "S\ "!$",8"DK""5g#67" " " "$!XeCc3S,H&IJ ! ! ! !F5 5' 5D 5S 5 5 5 5T hsm    
G       r-   rD   ),r1   r(   abcr   r   typingr   r   r   r   r	   r
   r   r   r   r   r   r   docutilsr   docutils.nodesr   r   r   docutils.parsers.rst.statesr   sphinx.addnodesr   sphinx.errorsr   sphinx.localer   sphinx.rolesr   sphinx.util.typingr   sphinx.buildersr   sphinx.environmentr   r   r5   r@   rD   r3   r-   r+   <module>r      sI     # # # # # # # #. . . . . . . . . . . . . . . . . . . . . . . . . . . .       8 8 8 8 8 8 8 8 8 8 / / / / / / ( ( ( ( ( ( % % % % % %       ! ! ! ! ! ! + + + + + + 4''''''333333! ! ! ! ! ! ! !4       U" U" U" U" U"C U" U" U"pw w w w w w w w w wr-   