B .Kc?@sdZddlmZmZmZmZmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZddlmZdd lmZdd lmZerdd lmZeeZe je d d dZ!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. ) TYPE_CHECKINGAnyDictListTupleTypeUnioncast)nodes)Node)Inliner)addnodes)BuildEnvironment)__)logging) TextlikeNode)ObjectDescription)nodereturncCsZt|dkrdSt|dkrBx$|ddD]}t|tjs*dSq*Wt|dtjrVdSdS)zCTrue if the node only contains one paragraph (and system messages).rFNT)len isinstancer Zsystem_message paragraph)rZsubnoder4lib/python3.7/site-packages/sphinx/util/docfields.py_is_single_paragraphs   rc @seZdZdZdZdZdeeedfeeeedddd Z e j ddddfeeee e eeeeed d d Ze j ddddfeeee e eeeeeed d dZeeeeeeefdddZdeeeefeeeeeejdddZdS)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 FrNT.)namenameslabelhas_argrolename bodyrolenamercCs(||_||_||_||_||_||_dS)N)rrrr r!r")selfrrrr r!r"rrr__init__5s zField.__init__) 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} ||| | St |d} | |||| |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.)r+F)Z refdomainZ refexplicitZreftypeZ reftargetr) AssertionErrorZ get_domainrolerloggerZwarningr Z pending_xrefZprocess_field_xrefrZget_source_liner inline)r#r!r%r&r'r(r)r*r+r.msgZrefnodelinenonsmessagesrrr make_xref>s"   zField.make_xrefc Cs|||||||||gS)N)r5) r#r!r%r&r'r(r)r*r+rrr make_xrefsXszField.make_xrefs)fieldargcontentrcCs||fS)Nr)r#r7r8rrr make_entry_szField.make_entry)typesr%itemr)r*r+rc 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, )r)r*r+rr)r(r)r*r+)r,r,)r field_namerTextextendr6r!rrr0r"astext field_bodyrfield) r#r:r%r;r)r*r+r7r8 fieldname fieldbodyrrr make_fieldbs     zField.make_field)rNTNN)NNN)__name__ __module__ __qualname____doc__ is_groupedis_typedstrrboolr$r literal_emphasisrrr rr r5rr6r9rr rBrErrrrr%s $ (,"rc sneZdZdZdZejZd ee edfeee ddfdd Z de ee efee eeeejd d d ZZS) 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 TrNF.)rrrr! can_collapsercst|||d|||_dS)NT)superr$rP)r#rrrr!rP) __class__rrr$szGroupedField.__init__)r:r%itemsr)r*r+rc Cstd|j}|}x`|D]X\} } t} | |j|j|| tj |||d| t d7} | | 7} |t d| 7}qWt |dkr|j rttj |d} td| d} td|| Std|} td|| S)Nr,)r)r*r+z -- rr)r r=r list_typerr?r6r!r literal_strongr> list_itemrrPr rArB)r#r:r%rSr)r*r+rCZlistnoder7r8parrVrDrrrrEs  zGroupedField.make_field)rNNF)NNN)rFrGrHrIrJr Z bullet_listrTrLrrMr$rrr rr rBrE __classcell__rr)rRrrOxs &rOc steZdZdZdZd eeedfeedfeeeeddfdd Zde ee e feee e e ejd 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 TrNF.)rr typenamesrr! typerolenamerPrcs$t|||||||_||_dS)N)rQr$rZr[)r#rrrZrr!r[rP)rRrrr$szTypedField.__init__)r:r%rSr)r*r+rc stttjdfdd }tdj}t|dkrZjrZ|d\} } || | } n0} x&|D]\} } | td|| | 7} qhWt d| } t d|| S)N)r7r8rc st}|jj|tjd|kr|td7}|}t |dkrt |dtjr|d }|jj |tj dn||7}|td7}|td7}||7}|S)N)r)z (rr)r)r*r+)z -- )r rr?r6r!r rUr>poprrr@r[rN)r7r8rW fieldtypetypename)r%r)r*r+r#r:rr handle_items   z*TypedField.make_field..handle_itemr,rr) rLr rr=rrrPrTrVrArB) r#r:r%rSr)r*r+r`rCr7r8ZbodynoderDr)r%r)r*r+r#r:rrEs"   zTypedField.make_field)rrNNNF)NNN)rFrGrHrIrKrLrrMr$rrr rr r rBrErXrr)rRrrYs2rYc@s^eZdZUdZeeeeeffe d<dddddZ e j ddd d Z ejddd d ZdS) DocFieldTransformerz Transforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. typemaprN) directivercCs||_||_dS)N)rcZget_field_type_maprb)r#rcrrrr$szDocFieldTransformer.__init__)rrcCs(x"|D]}t|tjr||qWdS)z,Transform all field list children of a node.N)rr field_list transform)r#rZchildrrr transform_alls  z!DocFieldTransformer.transform_allc! Cs|j}g}i}i}x tttj|D]}t|dksYnXt|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&Wt/}xt|D]l}t|tjrL||7}nN|\}}}| |j!i}|jjjjj}|jjj0} ||j1||jj||| |d 7}q0W|2|dS)z%Transform a single field list *node*.rrNr,)NNr<)r(r)cSs"g|]}t|tjtjfr|qSr)rr ZInliner>).0nrrr :sz1DocFieldTransformer.transform..T)Z translatable)r)r*r+)r,r,)3rbr rr rBrr-r=rAr@split ValueErrorgetrrZchildrenr rMupperr>appendrrYr6r[rcr%stateZdocumentZsettingsr)clearr?r setdefaultrKrsplitr0Z rawsourceparentsourcelinerJrrr r9rdr*rEZ replace_self)!r#rrbentriesZ groupindicesr:rBr=rAZfieldtype_namer7ZtypedescZ is_typefieldrr8Z new_fieldnameZ typed_fieldr&Zxrefsr_ZargtypeargnameZtranslatable_contentgroupZ new_entryZnew_listentryr^rSr+Z fieldtypesr)r*rrrres                  zDocFieldTransformer.transform)rFrGrHrIrrLrrrM__annotations__r$r Z desc_contentrfr rdrerrrrras raN)&rItypingrrrrrrrr Zdocutilsr Zdocutils.nodesr Zdocutils.parsers.rst.statesr Zsphinxr Zsphinx.environmentrZ sphinx.localerZ sphinx.utilrZsphinx.util.typingrZsphinx.directivesrZ getLoggerrFr/rArMrrrOrYrarrrrs"(           S,A