U \ShA@sdZddlmZddlZddlmZmZmZmZm Z ddl m Z ddl m Z mZddlmZddlmZdd lmZdd lmZdd lmZdd lmZdd lmZerddlmZee Z!dddddZ"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_CHECKINGAnyListTuplecast)nodes)ElementNode)Inliner)addnodes)BuildEnvironment)__)logging) get_node_line) TextlikeNode)ObjectDescriptionznodes.field_bodyboolnodereturncCsXt|dkrdSt|dkr@|ddD]}t|tjs(dSq(t|dtjrTdSdS)zCTrue if the node only contains one paragraph (and system messages).rFNT)len isinstancerZsystem_message paragraph)rZsubnoderH/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/util/docfields.py_is_single_paragraphs   rc @seZdZdZdZdZd$ddddddd d d d Zejd d d d fdddddddddd ddZ ejd d d d fdddddddddd ddZ ddddddZ d%ddddddd d!d"d#Z d S)&FieldaA 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 FrTstrtuple[str, ...]rNone)namenameslabelhas_argrolename bodyrolenamercCs(||_||_||_||_||_||_dSN)r#r$r%r&r'r()selfr#r$r%r&r'r(rrr__init__9s zField.__init__Nztype[TextlikeNode]z Node | NoneBuildEnvironment | NoneInliner | NoneElement | Noner ) r'domaintarget innernodecontnodeenvinlinerlocationrc  Cs|dk s t|dk|dkks(t||f|s:|p8|||S|||} | dksZ|dkr| dkr|dk rtd} tjt| |||dtjd|d||d} | |p|||7} ||| | Sd} |dk rt t t |} W5QRX| |||| |ig\} }t j|df| S)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)r5rF)Z refdomainZ refexplicitZreftypeZ reftarget)AssertionErrorZ get_domainrolerloggerwarningr Z pending_xrefZprocess_field_xref contextlibsuppress ValueErrorrrinline)r*r'r/r0r1r2r3r4r5r8msgZrefnodelinenonsmessagesrrr make_xrefIs,   zField.make_xrefz list[Node]c Cs|||||||||gSr))rC) r*r'r/r0r1r2r3r4r5rrr make_xrefsfs zField.make_xrefsztuple[str, list[Node]]fieldargcontentrcCs||fSr)r)r*rFrGrrr make_entrynszField.make_entrydict[str, list[Node]]tuple nodes.field)typesr/itemr3r4r5rc Cs|\}}td|j} |rJ| td7} | |j|j||tj|||dt|dkrt|dtjst|dtj rt|ddkrt|ddtjr|j|j ||d |d|||d}t dtj d|} td| | S)Nr r3r4r5rr)r2r3r4r5)rr)r field_namer%TextextendrDr'rrr>r(astext field_bodyrfield) r*rLr/rMr3r4r5rFrG fieldname fieldbodyrrr make_fieldqs:    zField.make_field)rrTrr)NNN) __name__ __module__ __qualname____doc__ is_groupedis_typedr+r literal_emphasisrCrDrHrXrrrrr)s4   rc sXeZdZdZdZejZddddddd d fd d ZdddddddddddZ 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!rr")r#r$r%r' can_collapsercst|||d|||_dS)NT)superr+ra)r*r#r$r%r'ra __class__rrr+szGroupedField.__init__NrIrJr,r-r.rKrLr/itemsr3r4r5rc Cstd|j}|}|D]X\} } t} | |j|j|| tj |||d| t d7} | | 7} |t d| 7}qt |dkr|j rttj |d} td| d} td|| Std|} td|| S)NrrO -- rr)rrPr% list_typerrRrDr'r literal_strongrQ list_itemrrarrTrU)r*rLr/rfr3r4r5rVZlistnoderFrGparrjrWrrrrXs&   zGroupedField.make_field)rrrF)NNN) rYrZr[r\r]rZ bullet_listrhr+rX __classcell__rrrcrr`s  r`c sVeZdZdZdZddddddddd d fd d ZdddddddddddZZS) 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!rr")r#r$ typenamesr%r' typerolenamerarcs$t|||||||_||_dSr))rbr+rnro)r*r#r$rnr%r'rorarcrrr+s zTypedField.__init__NrIrJr,r-r.rKrec sddddfdd }tdj}t|dkrXjrX|d\} } || | } n,} |D]\} } | td|| | 7} qdtd| } td|| S) Nr znodes.paragraphrEc st}|jj|tjd|kr|td7}|}t |dkrt |dtjr|d }|jj |tj dn||7}|td7}|td7}||7}|S)N)r3z (rrrO)rg)rrrRrDr'r rirQpoprrrSror_)rFrGrk fieldtypetypenamer/r3r4r5r*rLrr handle_items*   z*TypedField.make_field..handle_itemrrr) rrPr%rrarhrjrTrU) r*rLr/rfr3r4r5rurVrFrGZbodynoderWrrtrrXs     zTypedField.make_field)rrrrrF)NNN)rYrZr[r\r^r+rXrlrrrcrrms"rmc@sJeZdZUdZded<dddddZd dd d d Zd dd ddZdS)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]]typemaprr") directivercCs||_||_dSr))rxZget_field_type_maprw)r*rxrrrr+szDocFieldTransformer.__init__zaddnodes.desc_contentrcCs$|D]}t|tjr||qdS)z,Transform all field list children of a node.N)rr field_list transform)r*rchildrrr transform_alls z!DocFieldTransformer.transform_allznodes.field_listc" Cs|j}g}i}i}tttj|D]}t|dks8tttj|d}ttj|d}z| dd\} } Wn"t k r| d} } YnX| | d\} } t |rttj|d} | j}n|j}| dks| jt| kr| dd| dd}| r|d| 7}t||d<||| r"| r"|r"t|dkr"t|dtjr"tt| }|d }|j|j|jjpzd||d|jjjjjd}t |rttj|d} | | |q"||tjd|7}q"| j!}| rd d |D}|r"||"|i| <q"| j#r^z| $dd\}}Wnt k r@YnXt|g|"|i|<|} tj%|j&d d }|j'j|_|j'j(|_(|j'j)|_)||7}| j*r||krtt+t,tt-f|||}n t|||<| g|f}||| .| |g}|d|q"| .| |g}|| ||fq"t/}|D]v}t|tjrJ||7}nX|\}}}| |j!i}|jjjjj}|jjj0} |jjpd}!||j1||!||| |d 7}q.|2|dS)z%Transform a single field list *node*.rrNr)NNrN)r2r3cSs"g|]}t|tjtjfr|qSr)rrZInlinerQ).0nrrr bsz1DocFieldTransformer.transform..T)Z translatablerO)rr)3rwrrrrUrr7rPrTrSsplitr=getrrchildrenr&rupperrQappendrrmrDrorxr/stateZdocumentsettingsr3clearrRr# setdefaultr^rsplitr>Z rawsourceparentsourceliner]rrr rHryr4rXZ replace_self)"r*rrwentriesZ groupindicesrLrUrPrTZfieldtype_namerFZtypedescZ is_typefieldrrGZ new_fieldnameZ typed_fieldr0ZxrefsrsZargtypeargnameZtranslatable_contentgroupZ new_entryZnew_listentryrrrfr5Z fieldtypesr3r4r/rrrrz s                       zDocFieldTransformer.transformN)rYrZr[r\__annotations__r+r|rzrrrrrv s rv)'r\ __future__rr;typingrrrrrZdocutilsrZdocutils.nodesr r Zdocutils.parsers.rst.statesr Zsphinxr Zsphinx.environmentr Z sphinx.localerZ sphinx.utilrZsphinx.util.nodesrZsphinx.util.typingrZsphinx.directivesr getLoggerrYr9rrr`rmrvrrrrs(            d2N