o $as@@sdZddlmZmZmZmZmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZddlmZdd lmZdd lmZerNdd lmZeeZd e jd e fddZ!GdddZ"Gddde"Z#Gddde#Z$GdddZ%dS)a8 sphinx.util.docfields ~~~~~~~~~~~~~~~~~~~~~ "Doc fields" are reST field lists in object descriptions that will be domain-specifically transformed to a more appealing presentation. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. ) TYPE_CHECKINGAnyDictListTupleTypeUnioncast)nodes)Node)Inliner)addnodes)BuildEnvironment)__)logging) TextlikeNode)ObjectDescriptionnodereturncCsXt|dkrdSt|dkr |ddD] }t|tjsdSqt|dtjr*dSdS)zCTrue if the node only contains one paragraph (and system messages).rFNT)len isinstancer system_message paragraph)rsubnoder7/usr/lib/python3/dist-packages/sphinx/util/docfields.py_is_single_paragraphs   rc@s0eZdZdZdZdZ  d#dedeedfd ed ed ed ed dfddZ e j ddddfd ededede e dedededed efddZe j ddddfd ededede e dedededed eefddZdedeed eeeeffddZ  d$deeeefded edededed ejfd!d"ZdS)%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 FrNTnamenames.labelhas_argrolename bodyrolenamercCs(||_||_||_||_||_||_dSN)rr r!r"r#r$)selfrr r!r"r#r$rrr__init__:s  zField.__init__domaintarget innernodecontnodeenvinlinerlocationc Cs|dusJ|du|duksJ||f|s|p|||S|||} | dus-|durc| durF|durFd} | d7} tjt| |||dtjd|d||d} | |pW|||7} ||| | St |d} | |||| |ig\} }t j |dg| RS)Nz(Problem in %s domain: field is supposed z5to use role '%s', but that role is not in the domain.)r.F) refdomain refexplicitreftype reftargetr) get_domainroleloggerwarningrr pending_xrefprocess_field_xrefrget_source_liner inline)r&r#r(r)r*r+r,r-r.r5msgrefnodelinenonsmessagesrrr make_xrefCs&  zField.make_xrefc Cs|||||||||gSr%)rA) r&r#r(r)r*r+r,r-r.rrr make_xrefs]szField.make_xrefsfieldargcontentcCs||fSr%r)r&rCrDrrr make_entrydszField.make_entrytypesitemc 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/ r,r-r.rr)r+r,r-r.)r field_namer!TextextendrBr#rrr;r$astext field_bodyrfield) r&rFr(rGr,r-r.rCrD fieldname fieldbodyrrr make_fieldgs,  zField.make_field)rNTNNNNN)__name__ __module__ __qualname____doc__ is_groupedis_typedstrrboolr'r literal_emphasisrrr rr rArrBrErr rOrRrrrrr*sz     &rcseZdZdZdZejZ  ddede edfd ed ed e d df fd d Z  dde ee efdede dededed ejfddZZS) 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 TrNFrr .r!r# can_collapsercst|||d|||_dS)NT)superr'r^)r&rr r!r#r^ __class__rrr's zGroupedField.__init__rFr(itemsr,r-r.c 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)Nr/rI -- rr)r rJr! list_typerrLrBr#r literal_strongrK list_itemrr^r rNrO)r&rFr(rbr,r-r.rPlistnoderCrDparrfrQrrrrRs"  zGroupedField.make_field)rNNFrS)rTrUrVrWrXr bullet_listrdrZrr[r'rrr rr rOrR __classcell__rrr`rr]}s4 r]cseZdZdZdZ   ddedeedfd eedfd ed ed ed eddffdd Z  dde ee e fdedede de de dejfddZZS) 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 TrNFrr . typenamesr!r# typerolenamer^rcs$t|||||||_||_dSr%)r_r'rlrm)r&rr rlr!r#rmr^r`rrr's zTypedField.__init__rFr(rbr,r-r.c sdtdtdtjffdd }tdj}t|dkr/jr/|d\} } || | } n} |D]\} } | td|| | 7} q5t d| } t d|| S) NrCrDrc st}|jj|tjd|vrT|td7}|}t |dkrIt |dtjrI|d }|jj |tj dn||7}|td7}|td7}||7}|S)N)r,z (rrrI)rc)r rrLrBr#r rerKpoprrrMrmr\)rCrDrh fieldtypetypenamer(r,r-r.r&rFrr handle_items$   z*TypedField.make_field..handle_itemr/rr) rZr rrJr!rr^rdrfrNrO) r&rFr(rbr,r-r.rsrPrCrDbodynoderQrrrrrRs&    zTypedField.make_field)rrNNNFrS)rTrUrVrWrYrZrr[r'rrr rr r rOrRrjrrr`rrks< rkc@s\eZdZUdZeeeeeffe d<dddZ d e j ddfd d Z d ejddfd d ZdS)DocFieldTransformerz Transforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. typemap directiverrNcCs||_||_dSr%)rwget_field_type_maprv)r&rwrrrr'szDocFieldTransformer.__init__rcCs$|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_allc! Cs|j}g}i}i}tttj|D]z}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|jj||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]7}t|tjr||7}q|\}}}| |j i}|jjjjj}|jjj/} ||j0||jj||| |d 7}q|1|dS)z%Transform a single field list *node*.rrNr/)NNrH)r+r,cSs(g|]}t|tjst|tjr|qSr)rr InlinerK).0nrrr ?s  z1DocFieldTransformer.transform..T) translatablerI)2rvr rr rOrrJrNrMsplit ValueErrorgetrrchildrenr"r[upperrKappendrrkrBrmrwr(statedocumentsettingsr,clearrLr setdefaultrYrsplitr; rawsourceparentsourcelinerXrrr rEryr-rR replace_self)!r&rrventries groupindicesrFrOrJrNfieldtype_namerCtypedesc is_typefieldrrD new_fieldname typed_fieldr)xrefsrqargtypeargnametranslatable_contentgroup new_entrynew_listentryrprbr. fieldtypesr,r-rrrrzs                    zDocFieldTransformer.transform)rwrrN)rTrUrVrWrrZrrr[__annotations__r'r desc_contentr|r ryrzrrrrrus  ruN)&rWtypingrrrrrrrr docutilsr docutils.nodesr docutils.parsers.rst.statesr sphinxr sphinx.environmentr sphinx.localer sphinx.utilrsphinx.util.typingrsphinx.directiver getLoggerrTr6rNr[rrr]rkrurrrrs$(           S,A