3
T'ícÀ? ã @ sø d Z ddlmZmZmZmZmZmZmZm Z ddl
m Z ddl m
Z
ddlmZ ddlmZ ddlmZ ddlmZ dd lmZ dd
lmZ erdd lmZ ej e Z e j e d d
dZ!G dd dZ"G dd de"Z#G dd de#Z$G dd dZ%dS )z¨Utility 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_CHECKINGÚAnyÚDictÚListÚTupleÚTypeÚUnionÚcast)Únodes)ÚNode)ÚInliner)Úaddnodes)ÚBuildEnvironment)Ú__)Úlogging)Ú TextlikeNode)ÚObjectDescription)ÚnodeÚreturnc C sZ t | dkrdS t | dkrBx$| dd
D ]}t|tjs*dS q*W t| d tjrVdS dS )zCTrue if the node only contains one paragraph (and system messages).r Fé NT)ÚlenÚ
isinstancer
Zsystem_messageÚ paragraph)r Zsubnode© r ú7/tmp/pip-build-gk9425m9/sphinx/sphinx/util/docfields.pyÚ_is_single_paragraph s r c @ sö e Zd ZdZdZdZf ddddfeeedf eeeeddddZ e
j ddddfeeee e
eeeeed d
d Ze
j ddddfeeee e
eeeeee d d d
Zeee eeee f dddZdeeee f eeeeeejdddZdS )ÚFielda¼ A 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
FNT.)ÚnameÚnamesÚlabelÚhas_argÚrolenameÚ bodyrolenamer c C s( || _ || _|| _|| _|| _|| _d S )N)r r r r r! r" )Úselfr r r r r! r" r r r Ú__init__5 s zField.__init__) r! ÚdomainÚtargetÚ innernodeÚcontnodeÚenvÚinlinerÚlocationr c C sú |d k s t |d k|d kks(t ||f|s:|p8|||S |j|j|} | d ksZ|d krÂ| d kr|d k rtd}
tjt|
|||d tjd|d||d} | |pª|||7 } |j|j| | S t j
|d } | |||| |i g \}
}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_domainÚroler ÚloggerÚwarningr
Z pending_xrefZprocess_field_xrefr Zget_source_liner
Úinline)r# r! r% r& r' r( r) r* r+ r. ÚmsgZrefnodeÚlinenoÚnsÚmessagesr r r Ú make_xref> s"
zField.make_xrefc C s | j ||||||||gS )N)r6 ) r# r! r% r& r' r( r) r* r+ r r r Ú
make_xrefsX s zField.make_xrefs)ÚfieldargÚcontentr c C s ||fS )Nr )r# r8 r9 r r r Ú
make_entry_ s zField.make_entry)Útypesr% Úitemr) r* r+ r c
C sä |\}}t jd| j} |rJ| t jd7 } | j| j| j||t j|||d t|dkrÀt|d t jst|d t j rÀt|d dkrÀt|d d t jrÀ| j| j
||d j |d |||d}t j dt j
d| }
t jd| |
S )Nr, ú )r) r* r+ r r )r( r) r* r+ )r, r, )r
Ú
field_namer ÚTextÚextendr7 r! r r r1 r" ÚastextÚ
field_bodyr Úfield) r# r; r% r< r) r* r+ r8 r9 Ú fieldnameÚ fieldbodyr r r Ú
make_fieldb s
zField.make_field)NNN)Ú__name__Ú
__module__Ú __qualname__Ú__doc__Ú
is_groupedÚis_typedÚstrr Úboolr$ r
Úliteral_emphasisr r r r r r6 r r7 r: r r
rC rF r r r r r % s * (," r c sv e Zd ZdZdZejZf dddfee edf eee
dd fdd
Z d e ee
e f ee eeeejd d
d Z ZS )
Ú 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
TNF.)r r r r! Ú can_collapser c s t j|||d| || _d S )NT)Úsuperr$ rQ )r# r r r r! rQ )Ú __class__r r r$ s zGroupedField.__init__)r; r% Úitemsr) r* r+ r c C sÒ t jd| j}| j }x`|D ]X\} }
t j } | j| j| j|| tj |||d | t j
d7 } | |
7 } |t j d| 7 }q W t |dkr¸| j
r¸tt j |d } t jd| d }
t jd||
S t jd|}
t jd||
S )Nr, )r) r* r+ z -- r r )r
r> r Ú list_typer r@ r7 r! r
Úliteral_strongr? Ú list_itemr rQ r rB rC )r# r; r% rT r) r* r+ rD Zlistnoder8 r9 ÚparrW rE r r r rF s zGroupedField.make_field)NNN)rG rH rI rJ rK r
Z bullet_listrU rM r rN r$ r r r r r rC rF Ú
__classcell__r r )rS r rP x s * rP c
s e Zd ZdZdZf f ddddfeeedf eedf eeeedd fdd
Zd e ee
e f eee e
e ejd d
d Z ZS )
Ú
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
TNF.)r r Ú typenamesr r! Ú typerolenamerQ r c s$ t j||||| || _|| _d S )N)rR r$ r[ r\ )r# r r r[ r r! r\ rQ )rS r r r$ ¹ s zTypedField.__init__)r; r% rT r) r* r+ r c
s¤ t t tjd fdd }tjdj}t|dkrZjrZ|d \} }
|| |
} n0j } x&|D ] \} }
| tjd|| |
7 } qhW tj d| } tj
d|| S )N)r8 r9 r c
s t j }|jjj | tjd | kr¨|t jd7 }j| }t |dkrt
|d t jr|d j }|jjj |tj
d n||7 }|t jd7 }|t jd7 }||7 }|S )N)r) z (r r )r) r* r+ ú)z -- )r
r r@ r7 r! r
rV r? Úpopr r rA r\ rO )r8 r9 rX Ú fieldtypeÚtypename)r% r) r* r+ r# r; r r Ú handle_itemà s
z*TypedField.make_field.<locals>.handle_itemr, r r ) rM r
r r> r r rQ rU rW rB rC )
r# r; r% rT r) r* r+ ra rD r8 r9 ZbodynoderE r )r% r) r* r+ r# r; r rF À s " zTypedField.make_field)NNN)rG rH rI rJ rL rM r rN r$ r r r r r r
rC rF rY r r )rS r rZ ¤ s 4 rZ c @ sZ e Zd ZU dZeeeeef f dddddZ
e j dddd 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.
r N)Ú directiver c C s || _ |j | _d S )N)rc Zget_field_type_mapÚtypemap)r# rc r r r r$ ì s z DocFieldTransformer.__init__)r r c C s( x"|D ]}t |tjr| j| qW dS )z,Transform all field list children of a node.N)r r
Ú
field_listÚ transform)r# r Úchildr r r Ú
transform_allñ s
z!DocFieldTransformer.transform_allc ! C s® | j }g }i }i }x tttj |D ]ö}t|dks<tttj|d }ttj|d }y|j j
dd\} }
W n" t k
r |j d } }
Y nX |j | d
\} } t
|rÈttj|d }
|
j}n|j}| dksæ| jt|
krÜ| dd
j | dd
}|
r|d|
7 }tj||d< |j| | r&| r&|r&t|dkr&t|d tjr&tt| }|d j }|j|j| jj||d | jjj j j d}t
|rÀttj|d }
|
j |
j | q&|j |tjd| 7 }q&| j!}| r dd |D }|r&||j"|i |
< q&| j#r\y|
j$dd\}}W n t k
r> Y n X tj|g|j"|i |< |}
tj%|j&d
d }|j'j |_ |j'j(|_(|j'j)|_)||7 }| j*r ||krÂtt+t,tt-f ||| }n t|||< | g |f}|j| | j.|
|g}|d j| q&| j.|
|g}|j| ||f q&W tj/ }xt|D ]l}t|tjrL||7 }nN|\}} } |j |j!i } | jjj j j } | jjj0} ||j1| | jj| | | | d 7 }q0W |j2| dS )z%Transform a single field list *node*.é r r Nr, r= )r( r) c S s" g | ]}t |tjtjfr|qS r )r r
ZInliner? )Ú.0Únr r r ú
<listcomp>: s z1DocFieldTransformer.transform.<locals>.<listcomp>T)Z translatable)r) r* r+ )NN)r, r, )3rd r r r
rC r r- r> rB rA ÚsplitÚ
ValueErrorÚgetr r Úchildrenr rN Úupperr? Úappendr rZ r7 r\ rc r% ÚstateÚdocumentÚsettingsr) Úclearr@ r Ú
setdefaultrL Úrsplitr1 Z rawsourceÚparentÚsourceÚlinerK r r r r: re r* rF Z replace_self)!r# r rd ÚentriesZ groupindicesr; rC r> rB Zfieldtype_namer8 ZtypedescZ is_typefieldr r9 Z
new_fieldnameZ typed_fieldr& Zxrefsr` ZargtypeZargnameZtranslatable_contentÚgroupZ new_entryZnew_listÚentryr_ rT r+ Z
fieldtypesr) r* r r r rf ø s
z DocFieldTransformer.transform)rG rH rI rJ r rM r r rN rd r$ r
Z desc_contentrh r
re rf r r r r rb å s
rb N)&rJ Útypingr r r r r r r r Zdocutilsr
Zdocutils.nodesr Zdocutils.parsers.rst.statesr Zsphinxr
Zsphinx.environmentr Z
sphinx.localer Z sphinx.utilr Zsphinx.util.typingr Zsphinx.directivesr Ú getLoggerrG r/ rB rN r r rP rZ rb r r r r Ú<module> s" (
S,A