
    }c;                        d Z ddlZddlZddlZddlmZmZmZmZm	Z	m
Z
mZmZ ddlZddlmZ ddlmZmZmZ d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%m&Z& ddl'm(Z( ddl)m*Z* ddl+m,Z, ddl-m.Z.m/Z/m0Z0 erddl1m2Z2 ddl3m4Z4 ddl5m6Z6  e(j7        e8          Z9h 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;          ZAejB        ejC        ejD        ejE        ejF        d%ZG G d& d'e;          ZH G d( d)e;          ZI G d* d+e;          ZJ G d, d-e;          ZK G d. d/e;          ZL G d0 d1e;          ZM G d2 d3e;          ZN G d4 d5e          ZO G d6 d7ee;          ZP G d8 d9e;          ZQ G d: d;e;          ZR G d< d=e;          ZSd>d?d@eeTef         fdAZUdS )Bz:Docutils transforms used by Sphinx when reading documents.    N)TYPE_CHECKINGAnyDict	GeneratorListOptionalTuplecast)nodes)ElementNodeText)	TransformTransformer)ContentsFilter)SmartQuotes)normalize_language_tag)
smartchars)addnodes)Config)RemovedInSphinx60Warning)___)logging)new_document)format_date)NodeMatcherapply_source_workaroundis_smartquotable)Sphinx)StandardDomain)BuildEnvironment>   todayreleaseversionc                   ^    e Zd ZdZed	d            Zed
d            Zedefd            ZdS )SphinxTransformzA base class of Transforms.

    Compared with ``docutils.transforms.Transform``, this class improves accessibility to
    Sphinx APIs.
    returnr    c                     | j         j        S )z)Reference to the :class:`.Sphinx` object.)envappselfs    :lib/python3.11/site-packages/sphinx/transforms/__init__.pyr+   zSphinxTransform.app0   s     x|    r"   c                 $    | j         j        j        S )z3Reference to the :class:`.BuildEnvironment` object.)documentsettingsr*   r,   s    r.   r*   zSphinxTransform.env5   s     }%))r/   c                     | j         j        S )z)Reference to the :class:`.Config` object.)r*   configr,   s    r.   r4   zSphinxTransform.config:   s     xr/   N)r(   r    )r(   r"   )	__name__
__module____qualname____doc__propertyr+   r*   r   r4    r/   r.   r'   r'   )   s             X * * * X*     X  r/   r'   c                   \     e Zd ZU dZej        ed<   dZed         ed<   d	dZ	d
 fdZ
 xZS )SphinxTransformerz#
    A transformer for Sphinx.
    r1   Nr"   r*   r(   c                     || _         d S N)r*   )r-   r*   s     r.   set_environmentz!SphinxTransformer.set_environmentH   s    r/   c                    t          | j        t          j                  rYt          | j        j        d          s| j        r| j        | j        j        _        t                                                       d S 	 t          d          }| j        r| j        |j        _        || j        z  }|| _        t                                                       | j        d         | _        d S # | j        d         | _        w xY w)Nr*    r   )	
isinstancer1   r   hasattrr2   r*   superapply_transformsr   )r-   r1   	__class__s     r.   rE   z"SphinxTransformer.apply_transformsK   s    dmU^44 	14=1599 6dh 6-1X&*GG$$&&&&&1'++8 5,0HH%)DM) (((*** $a 0a 00000s   ;AC' 'C;)r*   r"   r(   N)r(   N)r5   r6   r7   r8   r   r1   __annotations__r*   r   r?   rE   __classcell__rF   s   @r.   r<   r<   @   s           n(,C$	%,,,   1 1 1 1 1 1 1 1 1 1r/   r<   c                   &    e Zd ZdZdZdeddfdZdS )DefaultSubstitutionszL
    Replace some substitutions if they aren't defined in the document.
       kwargsr(   Nc                    t           t          | j        j                  z
  }| j                            t
          j                  D ]~}|d         }||v rp| j        |         }|dk    r6|s4t          | j        j	        pt          d          | j        j                  }|                    t          j        |                     d S )Nrefnamer#   z	%b %d, %Y)language)default_substitutionssetr1   substitution_defsfindallr   substitution_referencer4   r   	today_fmtr   rP   replace_selfr   )r-   rM   	to_handlerefrO   texts         r.   applyzDefaultSubstitutions.applye   s    )C0O,P,PP	=(()EFF 	3 	3C)nG)# 3{7+g% Fd F&t{'<'N+040DF F FD  D!1!1222	3 	3r/   r5   r6   r7   r8   default_priorityr   r[   r:   r/   r.   rK   rK   ^   sH          3c 3d 3 3 3 3 3 3r/   rK   c                   &    e Zd ZdZdZdeddfdZdS )MoveModuleTargetszv
    Move module targets that are the first thing in a section to the section
    title.

    XXX Python specific
    rL   rM   r(   Nc                 X   t          | j                            t          j                            D ]w}|d         sd|v rh|j        j        t          j        u rP|j                            |          dk    r2|d         |j        d         dd<   |j        	                    |           xd S )Nidsismod   r   )
listr1   rT   r   targetparentrF   sectionindexremover-   rM   nodes      r.   r[   zMoveModuleTargets.apply|   s    ..u|<<== 	) 	)D; 4 )K)U]:) K%%d++q0) +/u+E"1Q3'""4(((	) 	)r/   r\   r:   r/   r.   r_   r_   s   sH          	)c 	)d 	) 	) 	) 	) 	) 	)r/   r_   c                   &    e Zd ZdZdZdeddfdZdS )HandleCodeBlocksz5
    Several code block related transformations.
    rL   rM   r(   Nc                     | j                             t          j                  D ]:}t	          d |j        D                       r|                    |j                   ;d S )Nc              3   J   K   | ]}t          |t          j                  V  d S r>   )rB   r   doctest_block).0childs     r.   	<genexpr>z)HandleCodeBlocks.apply.<locals>.<genexpr>   s?       % %e:eU%899 % % % % % %r/   )r1   rT   r   block_quoteallchildrenrW   rj   s      r.   r[   zHandleCodeBlocks.apply   su    M))%*;<< 	1 	1D % %m% % % % % 1!!$-000	1 	1r/   r\   r:   r/   r.   rm   rm      sH          1c 1d 1 1 1 1 1 1r/   rm   c                   &    e Zd ZdZdZdeddfdZdS )AutoNumberingzO
    Register IDs of tables, figures and literal_blocks to assign numbers.
    rL   rM   r(   Nc                 (   | j                             d          }| j                            t          j                  D ]R}|                    |          r;|                    |          &|d         g k    r| j                            |           Sd S )Nstdra   )	r*   
get_domainr1   rT   r   r   is_enumerable_nodeget_numfig_titlenote_implicit_target)r-   rM   domainrk   s       r.   r[   zAutoNumbering.apply   s    !%!4!4U!;!;M))%-88 	9 	9D))$// 9++D119K2%9 224888		9 	9r/   r\   r:   r/   r.   rx   rx      sH          9c 9d 9 9 9 9 9 9r/   rx   c                   &    e Zd ZdZdZdeddfdZdS )SortIdszA
    Sort section IDs so that the "id[0-9]+" one comes last.
    i  rM   r(   Nc                    | j                             t          j                  D ]_}t	          |d                   dk    rD|d         d                             d          r#|d         dd          |d         d         gz   |d<   `d S )Nra   rc   r   id)r1   rT   r   rg   len
startswithrj   s      r.   r[   zSortIds.apply   s    M))%-88 	A 	AD4;!# AUA(A(A$(G(G A"5k!""oeQ0@@U	A 	Ar/   r\   r:   r/   r.   r   r      sP          Ac Ad A A A A A Ar/   r   )zliteral-blockzdoctest-blockrawrh   imagec                   &    e Zd ZdZdZdeddfdZdS )ApplySourceWorkaroundz0
    Update source and rawsource attributes
    
   rM   r(   Nc                     | j                                         D ]B}t          |t          j        t          j        t          j        f          rt          |           Cd S r>   )r1   rT   rB   r   TextElementr   topicr   rj   s      r.   r[   zApplySourceWorkaround.apply   sX    M))++ 	. 	.D$!2EK MNN .'---	. 	.r/   r\   r:   r/   r.   r   r      sH          .c .d . . . . . .r/   r   c                   &    e Zd ZdZdZdeddfdZdS )AutoIndexUpgraderz[
    Detect old style (4 column based indices) and automatically upgrade to new style.
    rL   rM   r(   Nc                 z   | j                             t          j                  D ]}d|v rt	          d |d         D                       rpt          d          |d         z  }t                              ||           t          |d                   D ]&\  }}t          |          dk    r|dz   |d         |<   'd S )Nentriesc              3   <   K   | ]}t          |          d k    V  dS )   N)r   )rq   entrys     r.   rs   z*AutoIndexUpgrader.apply.<locals>.<genexpr>   s,      (V(VUUq(V(V(V(V(V(Vr/   zG4 column based index found. It might be a bug of extensions you use: %r)locationr   r>   )
r1   rT   r   rh   anyr   loggerwarning	enumerater   )r-   rM   rk   msgir   s         r.   r[   zAutoIndexUpgrader.apply   s    M))(.99 	= 	=DD  =S(V(Vd9o(V(V(V%V%V = G H HJNy/ZsT222 )$y/ : : = =HAu5zzQ =-2W_Y*	= 	=r/   r\   r:   r/   r.   r   r      sH          =c =d = = = = = =r/   r   c                   &    e Zd ZdZdZdeddfdZdS )ExtraTranslatableNodesz!
    Make nodes translatable
    r   rM   r(   Nc                     | j         j        fdt                                          D             sd S dt          dt
          ffd}| j                            |          D ]}d|d<   d S )Nc                 "    g | ]\  }}|v 	|S r:   r:   )rq   kvtargetss      r.   
<listcomp>z0ExtraTranslatableNodes.apply.<locals>.<listcomp>   s&    QQQdaALQQQQr/   rk   r(   c                 >    t          | t                              S r>   )rB   tuple)rk   target_nodess    r.   is_translatable_nodez:ExtraTranslatableNodes.apply.<locals>.is_translatable_node   s    dE,$7$7888r/   Ttranslatable)r4   gettext_additional_targetsTRANSLATABLE_NODESitemsr   boolr1   rT   )r-   rM   r   rk   r   r   s       @@r.   r[   zExtraTranslatableNodes.apply   s    +8QQQQ&8&>&>&@&@QQQ 	F	9t 	9 	9 	9 	9 	9 	9 	9 M))*>?? 	( 	(D#'D  	( 	(r/   r\   r:   r/   r.   r   r      sH          
(c 
(d 
( 
( 
( 
( 
( 
(r/   r   c                   &    e Zd ZdZdZdeddfdZdS )UnreferencedFootnotesDetectorz9
    Detect unreferenced footnotes and emit warnings
       rM   r(   Nc                    | j         j        D ]ad         g k    rd         d         | j         j        vr8t                              t          d          d         d         dd           b| j         j        D ]Rt          fd| j         j        D                       s+t                              t          d          dd           Sd S )	Nnamesr   z Footnote [%s] is not referenced.rY   footnote)typesubtyper   c              3   <   K   | ]}|d          d          k    V  dS )autoNr:   )rq   rY   rk   s     r.   rs   z6UnreferencedFootnotesDetector.apply.<locals>.<genexpr>  s0      ^^ss6{d6l2^^^^^^r/   zFootnote [#] is not referenced.)	r1   	footnotesfootnote_refsr   r   r   autofootnotesr   autofootnote_refsrj   s     @r.   r[   z#UnreferencedFootnotesDetector.apply   s    M+ 	. 	.DG}" .gq!)DD .r"DEEtG}UVGW$):(,  . . . M/ 	. 	.D^^^^dm>]^^^^^ .r"CDD$):(,  . . .	. 	.r/   r\   r:   r/   r.   r   r      sH          .c .d . . . . . .r/   r   c                   &    e Zd ZdZdZdeddfdZdS )DoctestTransformz.Set "doctest" style to each doctest_block node  rM   r(   Nc                     | j                             t          j                  D ]}|d                             d           d S )Nclassesdoctest)r1   rT   r   rp   appendrj   s      r.   r[   zDoctestTransform.apply  sI    M))%*=>> 	. 	.DO""9----	. 	.r/   r\   r:   r/   r.   r   r     sB        88.c .d . . . . . .r/   r   c                   D     e Zd ZdZdZdededdf fdZdeddfdZ xZS )	FigureAlignerz-
    Align figures to center by default.
    i  argsrM   r(   Nc                 n    t          j        dt                      t                      j        |i | d S )NzFigureAilgner is deprecated.)warningswarnr   rD   __init__)r-   r   rM   rF   s      r.   r   zFigureAligner.__init__  s?    4.	0 	0 	0$)&)))))r/   c                     t          t          j        t          j                  }| j                            |          D ]}|                    dd           d S )Naligndefault)r   r   tablefigurer1   rT   
setdefault)r-   rM   matcherrk   s       r.   r[   zFigureAligner.apply   sU    ek5<88M))'22 	0 	0DOOGY////	0 	0r/   )	r5   r6   r7   r8   r]   r   r   r[   rH   rI   s   @r.   r   r     s          *c *S *T * * * * * *
0c 0d 0 0 0 0 0 0 0 0r/   r   c                   &    e Zd ZdZdZdeddfdZdS )FilterSystemMessagesz&Filter system messages from a doctree.  rM   r(   Nc                 4   | j         j        rdnd}t          | j                            t
          j                            D ]U}|d         |k     rGt                              d|	                                           |j
                            |           Vd S )N      levelz%s [filtered system message])r4   keep_warningsrd   r1   rT   r   system_messager   debugastextrf   ri   )r-   rM   filterlevelrk   s       r.   r[   zFilterSystemMessages.apply*  s    ;4;aa!..u/CDDEE 	) 	)DG}{* );T[[]]KKK""4(((	) 	)r/   r\   r:   r/   r.   r   r   &  sB        00)c )d ) ) ) ) ) )r/   r   c                   :    e Zd ZdZej        Zdej        ddfdZ	dS )SphinxContentsFilterzx
    Used with BuildEnvironment.add_toc_from() to discard cross-file links
    within table-of-contents link nodes.
    rk   r(   Nc                     t           j        r>   )r   SkipNode)r-   rk   s     r.   visit_imagez SphinxContentsFilter.visit_image9  s
    nr/   )
r5   r6   r7   r8   r    ignore_node_but_process_childrenvisit_pending_xrefr   r   r   r:   r/   r.   r   r   2  sM          (H       r/   r   c                   z     e Zd ZdZdZdeddf fdZdefdZde	e
         deeeef         ddf         fd	Z xZS )
SphinxSmartQuoteszr
    Customized SmartQuotes to avoid transform for some extra node types.

    refs: sphinx.parsers.RSTParser
    i  rM   r(   Nc                     |                                  sd S | j        j        | _        t                                                       d S r>   )is_availabler4   smartquotes_actionrD   r[   )r-   rM   rF   s     r.   r[   zSphinxSmartQuotes.applyE  s@      "" 	F #'+"@r/   c                    | j         j                            dg           }| j         j                            dg           }| j        j        j        du rdS | j         j        du rdS | j        j        j	        |v rdS | j         j
        |v rdS | j        j        d         }t          |          D ]}|t          j        v r dS dS )Nbuilders	languagesFlanguage_codeT)r4   smartquotes_excludesgetr1   r2   smart_quotessmartquotesr+   buildernamerP   r*   r   r   quotes)r-   r   r   rP   tags        r.   r   zSphinxSmartQuotes.is_availableN  s    ;377
BGGK488bII	=!.%7 	5[$- 	5X"h. 	5[!Y. 	5 8$_5)(33 	 	Cj'' tt 5r/   txtnodesc              #      K   |D ]x}t          |          rOt          j        dk    r$t          j        ddt          |                    }n|                                }d|fV  `d|                                fV  yd S )N)r      z(?<=\x00)([-\\\'".`])z\\\1plainliteral)r   docutils__version_info__resubstrr   )r-   r   txtnoderZ   s       r.   
get_tokenszSphinxSmartQuotes.get_tokensg  s         	4 	4G(( 
4,7 ,6":GS\\RRDD">>++Do%%%% !'.."2"233333	4 	4r/   )r5   r6   r7   r8   r]   r   r[   r   r   r   r   r   r	   r   r   rH   rI   s   @r.   r   r   =  s         
 c d      d    244: 4)E#s(OTSW<W2X 4 4 4 4 4 4 4 4r/   r   c                   &    e Zd ZdZdZdeddfdZdS )DoctreeReadEventz!Emit :event:`doctree-read` event.ip  rM   r(   Nc                 F    | j                             d| j                   d S )Nzdoctree-read)r+   emitr1   )r-   rM   s     r.   r[   zDoctreeReadEvent.apply|  s     ndm44444r/   r\   r:   r/   r.   r  r  x  sB        ++5c 5d 5 5 5 5 5 5r/   r  c                   &    e Zd ZdZdZdeddfdZdS )ManpageLinkz&Find manpage section numbers and namesr   rM   r(   Nc                 6   | j                             t          j                  D ]s}d                    d |j        D                       }d}||dd}t          j        ||          }|r|                                }|j	        
                    |           td S )N c                 `    g | ]+}t          |t          j                  t          |          ,S r:   )rB   r   r   r   )rq   xs     r.   r   z%ManpageLink.apply.<locals>.<listcomp>  s>      >  >  >1#-a#<#< >A  >  >  >r/   z7^(?P<path>(?P<page>.+)[\(\.](?P<section>[1-9]\w*)?\)?)$rA   )pathpagerg   )r1   rT   r   manpagejoinrv   r   match	groupdict
attributesupdate)r-   rM   rk   r  patterninfors          r.   r[   zManpageLink.apply  s    M))(*:;; 
	) 
	)Dhh  >  >  >  >  > ? ?GPG##!# #D '**A %{{}}O""4((((
	) 
	)r/   r\   r:   r/   r.   r  r    sB        00)c )d ) ) ) ) ) )r/   r  c                   &    e Zd ZdZdZdeddfdZdS )GlossarySorterz.Sort glossaries that have the ``sorted`` flag.r   rM   r(   Nc                     | j                             t          j                  D ]A}|d         r7t	          t
          j        |d                   }t          |d           |d d <   Bd S )Nsortedr   c                     t          j        dt          t          j        |           d                                                                                   S )NNFDr   )unicodedata	normalizer
   r   termr   lower)items    r.   <lambda>z&GlossarySorter.apply.<locals>.<lambda>  sD    [%:UZ..q188::@@BB&D &D r/   )key)r1   rT   r   glossaryr
   r   definition_listr  )r-   rM   r"  r#  s       r.   r[   zGlossarySorter.apply  s~    --h.?@@ 	 	H! "&u'<hqk"J"J%+#D D& & &"	 	r/   r\   r:   r/   r.   r  r    sD        88 	c 	d 	 	 	 	 	 	r/   r  r+   r    r(   c                    |                      t                     |                      t                     |                      t                     |                      t                     |                      t
                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     |                      t                     ddddS )NbuiltinT)r%   parallel_read_safeparallel_write_safe)add_transformr   r   rK   r_   rm   r   r   rx   r   r   r   r   r  r  r  )r+   s    r.   setupr)    sS   +,,,,---*+++'(((&'''g&'''m$$$'(((*+++3444'(((&'''k"""n%%% "#  r/   )Vr8   r   r  r   typingr   r   r   r   r   r   r	   r
   r   r   docutils.nodesr   r   r   docutils.transformsr   r   docutils.transforms.partsr   docutils.transforms.universalr   docutils.utilsr   docutils.utils.smartquotesr   sphinxr   sphinx.configr   sphinx.deprecationr   sphinx.localer   r   sphinx.utilr   sphinx.util.docutilsr   sphinx.util.i18nr   sphinx.util.nodesr   r   r   sphinx.applicationr    sphinx.domain.stdr!   sphinx.environmentr"   	getLoggerr5   r   rQ   r'   r<   rK   r_   rm   rx   r   literal_blockrp   r   rh   r   r   r   r   r   r   r   r   r   r   r   r  r  r  r   r)  r:   r/   r.   <module>r>     s   @ @ 				      S S S S S S S S S S S S S S S S S S S S        . . . . . . . . . . 6 6 6 6 6 6 6 6 4 4 4 4 4 4 5 5 5 5 5 5 1 1 1 1 1 1 1 1 1 1 1 1                   7 7 7 7 7 7               - - - - - - ( ( ( ( ( ( T T T T T T T T T T 4))))))000000333333 
	8	$	$       i   .1 1 1 1 1 1 1 1<3 3 3 3 3? 3 3 3*) ) ) ) ) ) ) )*1 1 1 1 1 1 1 109 9 9 9 9O 9 9 9 	A 	A 	A 	A 	Ao 	A 	A 	A ((9^[  	. 	. 	. 	. 	.O 	. 	. 	.= = = = = = = ="( ( ( ( (_ ( ( (&. . . . .O . . ... . . . . . . .0 0 0 0 0O 0 0 0"	) 	) 	) 	) 	)? 	) 	) 	)    >   84 84 84 84 84_ 84 84 84v5 5 5 5 5 5 5 5) ) ) ) )/ ) ) )$    _   $x DcN      r/   