
    QjfDB                       U d Z ddlmZ ddlZddlmZmZ ddlZddl	Zddl
ZddlmZmZ ddlmZ ddlmZmZ ddlmZ dd	lmZmZ er&dd
lmZ ddlmZmZmZmZ ddlmZ ddl m!Z! ddl"m#Z#m$Z$ ejJ                  ejL                  ejN                  ejP                  ejJ                  ejP                  ejP                  ejJ                  ejN                  d	Z) G d de      Z* G d de*      Z+ G d de      Z, G d de      Z- G d de      Z. G d de.      Z/ G d de      Z0 G d de      Z1 G d  d!e      Z2	 	 d+	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d,d"Z3ejh                  jj                  jl                  jn                  ejh                  jj                  jl                  jp                  d#e3_9         e*ejt                  $       e+d%&       e,        e-        e.        e/        e0        e0        e1        e2       d'
Z;d(e<d)<   d-d*Z=y).z#Handlers for additional ReST roles.    )annotationsN)TYPE_CHECKINGAny)nodesutils)addnodes)___)ws_re)ReferenceRole
SphinxRole)Sequence)ElementNodeTextElementsystem_message)Sphinx)BuildEnvironment)ExtensionMetadataRoleFunction)	commanddfnkbd
mailheadermakevarmimetype	newsgroupprogramregexpc                       e Zd ZU dZej
                  Zded<   ej                  Z
ded<   	 	 	 	 	 d	 	 	 	 	 	 	 	 	 	 	 d fdZddZddZdd	Zdd
Z	 	 	 	 	 	 	 	 	 	 	 	 ddZ	 	 	 	 	 	 	 	 	 	 ddZ xZS )XRefRoleaA  
    A generic cross-referencing role.  To create a callable that can be used as
    a role function, create an instance of this class.

    The general features of this role are:

    * Automatic creation of a reference and a content node.
    * Optional separation of title and target with `title <target>`.
    * The implementation is a class rather than a function to make
      customization easier.

    Customization can be done in two ways:

    * Supplying constructor parameters:
      * `fix_parens` to normalize parentheses (strip from target, and add to
        title if configured)
      * `lowercase` to lowercase the target
      * `nodeclass` and `innernodeclass` select the node classes for
        the reference and the content node

    * Subclassing and overwriting `process_link()` and/or `result_nodes()`.
    ztype[Element]	nodeclassztype[TextElement]innernodeclassc                p    || _         || _        || _        ||| _        ||| _        t
        |           y N)
fix_parens	lowercasewarn_danglingr"   r#   super__init__)selfr&   r'   r"   r#   r(   	__class__s         ,lib/python3.12/site-packages/sphinx/roles.pyr*   zXRefRole.__init__G   sA     %"* &DN%"0D    c                    | j                   s1|j                  d      r|d d }| j                  j                  r|dz  }|j                  d      r|d d }||fS )Nz())has_explicit_titleendswithconfigadd_function_parentheses)r+   titletargets      r-   update_title_and_targetz XRefRole.update_title_and_targetY   sY    &&~~d#cr
{{33??4 CR[Ff}r.   c                |   d| j                   vr-d| j                   c| _        | _        d| j                  g| _        nV| j                   j	                  dd      \  | _        | _        d| j                  | j                   d| j                   g| _        | j
                  r| j                         S | j                         S )N: xref   -)name	refdomainreftypeclassessplitdisabledcreate_non_xref_nodecreate_xref_node)r+   s    r-   runzXRefRole.runf   s    dii+-tyy(DNDL"DLL1DL+/99??3+B(DNDL"DNNt~~6Fa~4VWDL==,,..((**r.   c                L   t        j                  | j                  dd        }| j                  rd| _        | j                  |d      \  }}| j                  | j                  || j                        }| j                  | j                  j                  | j                  |d      S )Nr<   Fr:   rA   is_ref)r   unescapetextr&   r1   r7   r#   rawtextrA   result_nodesinlinerdocumentenv)r+   rL   r6   nodes       r-   rD   zXRefRole.create_non_xref_nodes   s    ~~diim,??&+D#77bALD&""4<<t||"L  !6!6$u UUr.   c                   | j                   }| j                  }| j                  r|j                         }| j                  r| j                  ||      \  }}| j                  j                  | j                  | j                  | j                  | j                  d} | j                  | j                  fi |}| j                  |       | j                  | j                  || j                  ||      \  }}||d<   || j!                  | j                  || j"                        z  }| j%                  | j&                  j(                  | j                  |d      S )N)refdocr?   r@   refexplicitrefwarn	reftargetrH   TrI   )r6   r5   r'   lowerr&   r7   rQ   docnamer?   r@   r1   r(   r"   rM   set_source_infoprocess_linkr#   rA   rN   rO   rP   )r+   r6   r5   optionsrefnodes        r-   rE   zXRefRole.create_xref_node|   s&   

>>\\^F?? 88GME6 hh&&||22))
 !$..99W% ))HHgt66v
v  &4&&t||UDLL&QQ  !6!6'RV WWr.   c                2    |t        j                  d|      fS )zCalled after parsing title and target text, and creating the
        reference node (given in *refnode*).  This method can alter the
        reference node and must return a new (or the same) ``(title, target)``
        tuple.
         )r   sub)r+   rQ   r]   r1   r5   r6   s         r-   r[   zXRefRole.process_link   s     eiiV,,,r.   c                    |gg fS )a(  Called before returning the finished nodes.  *node* is the reference
        node if one was created (*is_ref* is then true), else the content node.
        This method can add other nodes and must return a ``(nodes, messages)``
        tuple (the usual return value of a role function).
         )r+   rP   rQ   rR   rJ   s        r-   rN   zXRefRole.result_nodes   s     vrzr.   )FFNNF)r&   boolr'   rc   r"   ztype[Element] | Noner#   ztype[TextElement] | Noner(   rc   returnNone)r5   strr6   rf   rd   tuple[str, str]rd   'tuple[list[Node], list[system_message]]rQ   r   r]   r   r1   rc   r5   rf   r6   rf   rd   rg   )
rP   znodes.documentrQ   r   rR   r   rJ   rc   rd   ri   )__name__
__module____qualname____doc__r   pending_xrefr"   __annotations__r   literalr#   r*   r7   rF   rD   rE   r[   rN   __classcell__r,   s   @r-   r!   r!   ,   s    .  (44I}4(-N%5 !*.37#  (	
 1  
$+VX<-- - !	-
 - - 
-&-=ELVZ	0r.   r!   c                  8     e Zd Z	 	 	 	 	 	 	 	 	 	 	 	 d fdZ xZS )AnyXRefRolec                x    t         |   |||||      }|j                  j                  |j                         |S r%   )r)   r[   
attributesupdateref_context)r+   rQ   r]   r1   r5   r6   resultr,   s          r-   r[   zAnyXRefRole.process_link   s:     %c74FvV!!#//2r.   rj   )rk   rl   rm   r[   rr   rs   s   @r-   ru   ru      sG      !	
   
 r.   ru   c                      e Zd ZddZddZy)PEPc                f   d| j                   j                  d      z  }dt        d      | j                  z  |dd fg}t	        j
                  |      }t        j                  dd|g      }| j                  j                  j                  |       	 | j                         }t        j                  ddd|d	g
      }| j                  r.|t        j                  | j                  | j                        z  }n(d| j                  z   }|t        j                  ||      z  }|||gg fS # t        $ r | j                  j                   j#                  t%        d      | j                  z  | j&                        }| j                  j)                  | j*                  | j*                  |      }	|	g|gfcY S w xY w)Nindex-%sindexsinglez$Python Enhancement Proposals; PEP %sr:   entriesidsFpepinternalrefurirA   zPEP zinvalid PEP number %sline)rQ   new_serialnor	   r6   r   r   r   rO   rP   note_explicit_target	build_uri	referencer1   strongr5   
ValueErrorreportererrorr
   linenoproblematicrM   
r+   	target_idr   r   r6   r   r   r5   msgprbs
             r-   rF   zPEP.run   s   !6!6w!??	 89DKKG
 w/b"9+6226:	 ^^%FBvX]W^_I&&U\\$**djjAA	+U\\%77	 vy)2--  	 ,,''--*+dkk9 . C ,,**4<<sKC53%<	 s   BD& &BF0/F0c                   | j                   j                  j                  j                  }| j                  j                  dd      }t        |      dk(  r|dt        |d         |d   fz  z   S |dt        |d         z  z   S )N#r<      zpep-%04d/#%sr   z	pep-%04d/)rO   rP   settingspep_base_urlr6   rB   lenintr+   base_urlrets      r-   r   zPEP.build_uri   sw    <<((11>>kkQ's8q=nCFSV/DDDDkCAK777r.   Nrh   rd   rf   rk   rl   rm   rF   r   rb   r.   r-   r|   r|      s    .B8r.   r|   c                      e Zd ZddZddZy)RFCc                T   d| j                   j                  d      z  }dd| j                  z  |dd fg}t        j                  |      }t        j                  dd|g      }| j                  j                  j                  |       	 | j                         }t        j                  ddd|d	g
      }| j                  r.|t        j                  | j                  | j                        z  }n(d| j                  z   }|t        j                  ||      z  }|||gg fS # t        $ r | j                  j                  j!                  t#        d      | j                  z  | j$                        }| j                  j'                  | j(                  | j(                  |      }	|	g|gfcY S w xY w)Nr~   r   r   zRFC; RFC %sr:   r   r   Frfcr   zRFC zinvalid RFC number %sr   )rQ   r   r6   r   r   r   rO   rP   r   r   r   r1   r   r5   r   r   r   r
   r   r   rM   r   s
             r-   rF   zRFC.run   sq   !6!6w!??	mdkk99b$OPw/b"9+6226:	 ^^%FBvX]W^_I&&U\\$**djjAA	+U\\%77	 vy)2--  	 ,,''--*+dkk9 . C ,,**4<<sKC53%<	 s   	BD BF'&F'c                \   | j                   j                  j                  j                  }| j                  j                  dd      }t        |      dk(  r1|| j                   j                  t        |d         z  z   dz   |d   z   S || j                   j                  t        |d         z  z   S )Nr   r<   r   r   )	rO   rP   r   rfc_base_urlr6   rB   r   rfc_urlr   r   s      r-   r   zRFC.build_uri  s    <<((11>>kkQ's8q=dll22SQ[@@3FQOOdll22SQ[@@@r.   Nrh   r   r   rb   r.   r-   r   r      s    .2Ar.   r   c                  8    e Zd Z ej                  d      ZddZy)GUILabelz(?<!&)&(?![&\s])c                   t        j                  | j                  | j                  g      }| j                  j                  | j                        }|t        j                  |j                  d            z  }|D ]f  }|j                  dd      }t        j                  |d         }t        j                  dd|dg      }||z  }|t        j                  |dd        z  }h |gg fS )	N)rM   rA   r   z&&&r:   acceleratorrH   r<   )
r   inlinerM   r>   amp_rerB   rL   Textpopreplace)r+   rR   spansspanletterr   s         r-   rF   zGUILabel.run  s    ||DLL499+F!!$)),

599Q<(( 	)D<<c*DZZQ(F,,r2vOKKDEJJtABx((D	) vrzr.   Nrh   )rk   rl   rm   recompiler   rF   rb   r.   r-   r   r     s    RZZ+,Fr.   r   c                  $     e Zd ZdZd fdZ xZS )MenuSelectionu   ‣c                v    | j                   j                  d| j                        | _         t        |          S )Nz-->)rL   r   BULLET_CHARACTERr)   rF   )r+   r,   s    r-   rF   zMenuSelection.run&  s-    II%%eT-B-BC	w{}r.   rh   )rk   rl   rm   r   rF   rr   rs   s   @r-   r   r   #  s    . r.   r   c                  @    e Zd Z ej                  d      ZddZddZy)EmphasizedLiteralz(\\\\|\\{|\\}|{|})c                    | j                  | j                        }t        j                  | j                  dg|| j
                  j                         | j
                  gd}|gg fS )Nr:   )rolerA   )parserL   r   rq   rM   r>   rX   )r+   childrenrR   s      r-   rF   zEmphasizedLiteral.run.  s\    ::dii(}}LL"
'
.2iioo.?$))
 vrzr.   c                <   g }dg}| j                   j                  |      D ]1  }|dk(  r|dxx   dz  cc<   |dk(  r6t        |      dk\  r|d   dk(  r|dxx   dz  cc<   @|j                  d       R|d	k(  rt        |      d
k(  rt|d   dk(  rlt        |d         dkD  r[|d   r'|j	                  t        j                  |d                |j	                  t        j                  |d   |d                dg}|j	                  d	       dj                  |      g}|dk(  r|dxx   dz  cc<   |dk(  r|dxx   d	z  cc<   %|dxx   |z  cc<   4 dj                  |      r5dj                  |      }|j	                  t        j                  |             |S )Nr:   z\\\{r   r0   )r   r:   }   r<   r   z\{z\})		parens_rerB   r   extendappendr   r   emphasisjoin)r+   rL   rz   stackparts        r-   r   zEmphasizedLiteral.parse6  su   NN((. 	"Dv~b	T!	u:?uRyC'7"I$I LL+u:?uQx33uQx=1;LQxejjq&:;MM%..q58"DEDE LL%WWU^,Eb	S 	b	S 	b	T!	3	"6 775>775>DMM%**T*+r.   Nrh   )rL   rf   rd   z
list[Node])rk   rl   rm   r   r   r   rF   r   rb   r.   r-   r   r   +  s    

01I$r.   r   c                  N    e Zd Z ej                  dej
                        ZddZy)Abbreviationz	\((.*)\)$c                d   | j                   j                         }| j                  j                  | j                        }|r@| j                  d |j                          j                         }|j                  d      |d<   n| j                  }t        j                  | j                  |fi |gg fS )Nr<   explanation)r\   copyabbr_researchrL   startstripgroupr   abbreviationrM   )r+   r\   matchedrL   s       r-   rF   zAbbreviation.run`  s    ,,##%,,%%dii099.w}}/557D%,]]1%5GM"99D""4<<AABBFFr.   Nrh   )rk   rl   rm   r   r   DOTALLr   rF   rb   r.   r-   r   r   ]  s    bjjryy1G	Gr.   r   c                  8    e Zd Z ej                  d      ZddZy)Manpagez5^(?P<path>(?P<page>.+)[(.](?P<section>[1-9]\w*)?\)?)$c                d   t        j                  d| j                        }| j                  j	                  |      x}r|j                         }n||dd}| j                  r| j                  dd  n| j                  }| j                  sa| j                  j                  rK | j                  j                  j                  di |}t        j                  d|| j                  g|      }nt        j                  |      }t        j                   | j"                  d|fd| j                  gi|}|gg fS )Nr_   r:   )pathpagesectionr<   )rA   r   rA   rb   )r   r`   r6   _manpage_rematch	groupdictrC   r5   r3   manpages_urlformatr   r   r>   r   r   manpagerM   )r+   r   minforL   uriinnerrR   s           r-   rF   zManpage.runo  s    ))C-  &&w//1/;;=D#WDD "&tzz!"~DJJ}}!9!91$++**119D9COOBtyyk#NEJJt$Eb%U$))UPTUvrzr.   Nrh   )rk   rl   rm   r   r   r   rF   rb   r.   r-   r   r   l  s    "**UVKr.   r   c                z   |i }|j                         }t        j                  j                  j                  j                  |       |j                  dd      }dg}|r|j                  d       d|v r|j                  |d          |r||vr|j                  |       t        j                  ||||      }	|	gg fS )Nlanguager:   code	highlightrA   )rA   r   )r   docutilsparsersrstrolesset_classesgetr   r   r   rq   )
r>   rM   rL   r   rO   r\   contentr   rA   rR   s
             r-   	code_roler     s     llnG**73{{:r*HhG{#Gwy)*HG+x ==$(KD62:r.   )classr   )r"   T)r(   )
downloadanyr   r   guilabelmenuselectionfilesampabbrr   zdict[str, RoleFunction]specific_docrolesc                N   ddl m} t        j                         D ]?  \  }}|j	                  ||      }|j                  ||d|gi      }|j                  ||       A t        j                         D ]  \  }}|j                  ||        |j                  dt               ddddS )Nr   )r   rA   r   builtinT)versionparallel_read_safeparallel_write_safe)
docutils.parsers.rstr   generic_docrolesitemsGenericRole
CustomRoleregister_local_roler  register_canonical_roler   )appr   rolenamer"   genericr   funcs          r-   setupr    s    */557 2)##Hi8'Iz3JK!!(D12
 ,113 2$!!(D12
 
!!&)4 "# r.   )Nrb   )r>   rf   rM   rf   rL   rf   r   r   rO   z#docutils.parsers.rst.states.Inlinerr\   zdict[str, Any] | Noner   zSequence[str]rd   ri   )r  r   rd   r   )>rn   
__future__r   r   typingr   r   docutils.parsers.rst.directivesr   docutils.parsers.rst.rolesdocutils.parsers.rst.statesr   r   sphinxr   sphinx.localer	   r
   sphinx.utilr   sphinx.util.docutilsr   r   collections.abcr   docutils.nodesr   r   r   r   sphinx.applicationr   sphinx.environmentr   sphinx.util.typingr   r   literal_strongr   rq   literal_emphasisr
  r!   ru   r|   r   r   r   r   r   r   r   r   r   
directivesclass_option	unchangedr\   download_referencer  rp   r  rb   r.   r-   <module>r)     s   ) " 	 % & ! " !    :(II)3B &&>>==++&&))**&&mm
  E} EP( (8- (8V A-  AFz $H /
 /dG: Gm h &*
  	
 1 #  -: !!,,99  $$//99	  8#>#>?T*55
"_Ny. *  r.   