o NiE@sdZddlmZddlZddlmZmZmZddlm Z ddl m Z m Z ddl mZddlmZdd lmZdd lmZerVdd lmZdd lmZdd lmZddlmZeeZdddZ GdddZ!Gddde!Z"Gddde"Z#GdddZ$dS)zUtility code for "Doc fields". "Doc fields" are reST field lists in object descriptions that will be domain-specifically transformed to a more appealing presentation. ) annotationsN) TYPE_CHECKINGAnycast)nodes)ElementNode)addnodes)__)logging) get_node_line)Inliner)ObjectDescription)BuildEnvironment) TextlikeNodenodenodes.field_bodyreturnboolcCsPt|dkrdSt|dkr |ddD] }t|tjsdSqt|dtjS)zCTrue if the node only contains one paragraph (and system messages).rFN)len isinstancersystem_message paragraph)rsubnoderI/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/util/docfields.py_is_single_paragraphs   rc@szeZdZdZdZdZ     d2d3ddZejddddfd4d!d"Z ejddddfd5d$d%Z d6d)d*Z   d7d8d0d1Z dS)9FieldaA doc field that is never grouped. It can have an argument or not, the argument can be linked using a specified *rolename*. Field should be used for doc fields that usually don't occur more than once. The body can be linked using a specified *bodyrolename* if the content is just a single inline or text node. Example:: :returns: description of the return value :rtype: description of the return type FrTnamestrnamestuple[str, ...]labelhas_argrrolename bodyrolenamerNonecCs(||_||_||_||_||_||_dSN)r r"r$r%r&r')selfr r"r$r%r&r'rrr__init__:s   zField.__init__Ndomaintarget innernodetype[TextlikeNode]contnode Node | NoneenvBuildEnvironment | NoneinlinerInliner | NonelocationElement | Nonerc Cs,|dusJ|du|duksJ||f|s|p|||S|||} | dus-|dura| durD|durDtd} tjt| |||dtjd|d||d} | |pU|||7} ||| | Sd} |durt t  t |} Wdn1s{wY| |||| |ig\} }t j |dg| RS)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)r6rF) refdomain refexplicitreftype reftarget) get_domainroler loggerwarningr pending_xrefprocess_field_xref contextlibsuppress ValueErrorr rinline)r*r&r,r-r.r0r2r4r6r>msgrefnodelinenonsmessagesrrr make_xrefJs8   zField.make_xref list[Node]c Cs|||||||||gSr))rL) r*r&r,r-r.r0r2r4r6rrr make_xrefsus zField.make_xrefsfieldargcontenttuple[str, list[Node]]cCs||fSr)r)r*rOrPrrr make_entryszField.make_entrytypesdict[str, list[Node]]itemtuple nodes.fieldc Cs|\}}td|j} |r%| td7} | |j|j||tj|||dt|dkr`t|dtjsMt|dtj r`t|ddkr`t|ddtjr`|j|j ||d |d|||d}t dtj ddg|R} td| | S)Nr r2r4r6rr)r0r2r4r6)r field_namer$TextextendrNr&rrrFr'astext field_bodyrfield) r*rSr,rUr2r4r6rOrP fieldname fieldbodyrrr make_fieldsD    zField.make_field)rrTrr)r r!r"r#r$r!r%rr&r!r'r!rr()r&r!r,r!r-r!r.r/r0r1r2r3r4r5r6r7rr)r&r!r,r!r-r!r.r/r0r1r2r3r4r5r6r7rrM)rOr!rPrMrrQNNN)rSrTr,r!rUrVr2r3r4r5r6r7rrW) __name__ __module__ __qualname____doc__ is_groupedis_typedr+r literal_emphasisrLrNrRrbrrrrr)s6   0 rcsHeZdZdZdZejZ    d!d"fdd Z   d#d$dd Z Z S)% GroupedFielda A doc field that is grouped; i.e., all fields of that type will be transformed into one field with its body being a bulleted list. It always has an argument. The argument can be linked using the given *rolename*. GroupedField should be used for doc fields that can occur more than once. If *can_collapse* is true, this field will revert to a Field if only used once. Example:: :raises ErrorClass: description when it is raised TrrFr r!r"r#r$r& can_collapserrr(cst|||d|||_dS)NT)superr+rl)r*r r"r$r&rl __class__rrr+s zGroupedField.__init__NrSrTr,itemsrVr2r3r4r5r6r7rWc Cstd|j}|}|D],\} } t} | |j|j|| tj |||d| t d7} | | 7} |t d| 7}q t |dkrZ|j rZttj |d} td| d} td|| Std|} td|| S)NrrY -- rr)rrZr$ list_typerr\rNr&r literal_strongr[ list_itemrrlrr^r_)r*rSr,rpr2r4r6r`listnoderOrPparrtrarrrrbs0    zGroupedField.make_field)rrrF) r r!r"r#r$r!r&r!rlrrr(rcrSrTr,r!rprVr2r3r4r5r6r7rrW) rdrerfrgrhr bullet_listrrr+rb __classcell__rrrnrrks rkcsFeZdZdZdZ      d#d$fdd Z   d%d&d!d"ZZS)' TypedFieldaa A doc field that is grouped and has type information for the arguments. It always has an argument. The argument can be linked using the given *rolename*, the type using the given *typerolename*. Two uses are possible: either parameter and type description are given separately, using a field from *names* and one from *typenames*, respectively, or both are given using a field from *names*, see the example. Example:: :param foo: description of parameter foo :type foo: SomeClass -- or -- :param SomeClass foo: description of parameter foo TrrFr r!r"r# typenamesr$r& typerolenamerlrrr(cs$t|||||||_||_dSr))rmr+r{r|)r*r r"r{r$r&r|rlrnrrr+s  zTypedField.__init__NrSrTr,rprVr2r3r4r5r6r7rWc sd fdd }td j}t|d kr(jr(|d \} } || | } n} |D]\} } | td || | 7} q.td | } td || S) NrOr!rPrMrnodes.paragraphc st}|jj|tjd|vrT|td7}|}t |dkrIt |dtjrI|d }|jj |tj dn||7}|td7}tdd|D}|rj|td 7}||7}|S) N)r2z (rrrY)css|] }|VqdSr))r]strip).0crrr Bsz=TypedField.make_field..handle_item..rq)rrr\rNr&r rsr[poprrr]r|rjany)rOrPrv fieldtypetypename has_contentr,r2r4r6r*rSrr handle_item%s:   z*TypedField.make_field..handle_itemrrr)rOr!rPrMrr}) rrZr$rrlrrrtr^r_) r*rSr,rpr2r4r6rr`rOrPbodynoderarrrrbs #    zTypedField.make_field)rrrrrF)r r!r"r#r{r#r$r!r&r!r|r!rlrrr(rcrw)rdrerfrgrir+rbryrrrnrrzsrzc@s8eZdZUdZded<ddd Zdd d ZdddZdS)DocFieldTransformerz Transforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. zdict[str, tuple[Field, bool]]typemap directiverrr(cCs||_||_dSr))rget_field_type_mapr)r*rrrrr+\szDocFieldTransformer.__init__raddnodes.desc_contentcCs$|D] }t|tjr||qdS)z,Transform all field list children of a node.N)rr field_list transform)r*rchildrrr transform_allas   z!DocFieldTransformer.transform_allnodes.field_listc" Cs|j}g}i}i}tttj|D]|}t|dksJttj|d}ttj|d}z | dd\} } Wnt yH|d} } Ynw| | d\} } t |rattj |d} | j}n|j}| duso| jt| kr| dd| dd}| r|d| 7}t||d<||| r| r|rt|dkrt|dtjrtt| }|d}|j|j|jjpd||d|jjjjjd}t |rttj |d} | | |n||tj ddg|R7}q| j }| rd d |D}|r||!|i| <q| j"r-z | #dd\}}Wn t yYnwt|g|!|i|<|} tj$|j%d d }|j&j|_|j&j'|_'|j&j(|_(||7}| j)r||vr`tt*t+tt,f|||}nt|||<| g|f}||| -| |g}|d|q| -| |g}|| ||fqt.}|D]<}t|tjr||7}q|\}}}| |j i}|jjjjj}|jjj/} |jjpd}!||j0||!||| |d 7}q|1|dS)z%Transform a single field list *node*.rrNr)NNrX)r0r2cSs"g|] }t|tjtjBr|qSr)rrInliner[)rnrrr s z1DocFieldTransformer.transform..T) translatablerY)2rrlistrr_rrZr^r]splitrEgetrrchildrenr%rupperr[appendrrzrNr|rr,statedocumentsettingsr2clearr\r setdefaultrirsplitrF rawsourceparentsourcelinerhrVrrrRrr4rb replace_self)"r*rrentries groupindicesrSr_rZr^fieldtype_namerOtypedesc is_typefieldrrP new_fieldname typed_fieldr-xrefsrargtypeargnametranslatable_contentgroup new_entrynew_listentryrrpr6 fieldtypesr2r4r,rrrrhs                     zDocFieldTransformer.transformN)rrrr()rrrr()rrrr()rdrerfrg__annotations__r+rrrrrrrTs   r)rrrr)%rg __future__rrCtypingrrrdocutilsrdocutils.nodesrrsphinxr sphinx.localer sphinx.utilr sphinx.util.nodesr docutils.parsers.rst.statesr sphinx.directivesrsphinx.environmentrsphinx.util.typingr getLoggerrdr?rrrkrzrrrrrs,             A\