L i[dZddlZddlZddlZddlZddlmZddlmZddl m Z m Z ddl Z ddl Z dZGddZGd d eZed gd ZGd de ZddZdZddZGddeZGddeZy)aKExtract reference documentation from the NumPy source tree. Copyright (C) 2008 Stefan van der Walt , Pauli Virtanen Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. N)warn) namedtuple)CallableMappingc|r,|djs|d=|r|djs|r,|djs|d=|r|djs|S)z.is_emptyiszz|# #r)r+r3)rr7s r read_to_next_empty_linezReader.read_to_next_empty_linefs& %%' $%%h//rc*d}|j|S)Ncp|jxr%t|jt|k(Sr)r r.lstripr6s r is_unindentedz:Reader.read_to_next_unindented_line..is_unindentedos'JJLFc$++-&8CI&E Gr)r3)rr<s r read_to_next_unindented_linez#Reader.read_to_next_unindented_linens H%%m44rcr|j|zt|jkr||j|zSyNr%r-rs r peekz Reader.peekss0 77Q;TYY '! $ $rcVdj|jj Sr?)joinrr r"s r r7zReader.is_emptyys!77499%++---rN)r)__name__ __module__ __qualname____doc__rrrr(r+r&r3r8r=r@r7rr rr1s> )05  .rrceZdZdZy) ParseErrorc^|jd}t|dr|d|j}|S)Nr docstring in )argshasattrrK)rmessages r __str__zParseError.__str__~s3))A, 4 % dnn%78GrN)rCrDrErPrGrr rIrI}srrI Parameter)nametypedescc$eZdZdZiddddgdgdgdgdgd gd gd gd gd gdgdgdgdgdddddiiZifdZdZdZdZdZ dZ dZ dZ dZ dAdZdZd Zd!Zd"ezezd#zezd$zZej'd%d&Zej'd'd(Zd)Zej.d*ezd+zZej.d,ezd-zezd.zd$zd/zezZd0Zd1Zd2Zd3Zd4ZdBd5ZdCd6Z dDd7Z!d8Z"d9Z#d:Z$d;Z%d<Z&d=Z'd>Z(dEd?Z)y@)FNumpyDocStringzParses a numpydoc string to an abstract representation Instances define a mapping from section title to structured data. Signaturer%SummaryExtended Summary ParametersReturnsYieldsReceivesRaisesWarnsOther Parameters AttributesMethodsSee AlsoNotesWarnings ReferencesExamplesindexc |}tj|jd}t||_t j |j|_ |jy#t$r }||_ d}~wwxYwNr) textwrapdedentrr_doccopydeepcopysections _parsed_data_parserIrK)rrKconfigorig_docstringes r rzNumpyDocString.__init__si"OOI.44T: 9%  MM$--8  KKM (AK  sA-- B6A>>Bc |j|Sr)rq)rkeys r rzNumpyDocString.__getitem__s  %%rcl||jvr|jd|dy||j|<y)NzUnknown section Ferror)rq_error_location)rrwvals r __setitem__zNumpyDocString.__setitem__s; d'' '  #3C5!9 G%(D  c "rc,t|jSr)iterrqr"s r __iter__zNumpyDocString.__iter__sD%%&&rc,t|jSr)r.rqr"s r __len__zNumpyDocString.__len__s4$$%%rc|jj|jjry|jjj }|j dry|jjdj }|j dt |zxs|j dt |zS)NF .. index::Tr$-=)rmr+r&r@r startswithr.)rl1l2s r _is_at_sectionzNumpyDocString._is_at_sections **, 99==? YY^^  # # % == & YY^^A  $ $ &}}SR[)GR]]3s2w;-GGrcd}d}t|D]\}}|jsnt|dddD]\}}|jsn||t||z S)Nrr) enumerater r.)rdocijr2s r _stripzNumpyDocString._stripst   ~ GAtzz| !TrT+ GAtzz| 1SXaZ  rc||jj}|js|jjsw|jj dj s|dgz }||jjz }|js|jjsw|S)Nrr%)rmr8rr&r@r )rsections r _read_to_next_sectionz$NumpyDocString._read_to_next_sections))335%%' 99>>"%++-B4 tyy88: :G %%'  rc#RK|jjs|j}|dj}|j dr ||ddfn/t |dkr t n||j|ddf|jjsyyw)Nr..r$)rmr&rr rr. StopIterationr)rrrRs r _read_sectionszNumpyDocString._read_sectionss))--/--/D7==?Dt$DHn$TQ##DKKQR111))--/s B"B'%B'cpt|}g}|js|jj}d|vr|j ddd\}}n |rd|}}n|d}}|j }t |}t|}|jt||||js|S)N : rr%) rr&r(r rr= dedent_linesr appendrQ) rcontentsingle_element_is_typerparamsheaderarg_namearg_typerTs r _parse_param_listz NumpyDocString._parse_param_lists 7O%%'VVX^^%F%+\\%%8!%<"())+VhH)/hH113D%D$T*D MM)Hh= >%%'  rz:(?P\w+):z'`(?P(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P[a-zA-Z0-9_\.-]+)(|)rolerolenextrRnamenextz/(?P\s*:(\s+(?P\S+.*))?)?\s*$z^\s*z\s*z^\s*(?Pz(?P([,]\s+z)*)z(?P[,\.])?rcg}fd}g}|D]_}|jsjj|}d}|rK|jd}|jdr)|r'j d|j d|fzd|s1|j dr |j|j|rg}|jd } | jsnP|| \} } } |j| | f| | dj} | r| d d k(r| d dj} attd|g}|j||fTt|d |S)z func_name : Descriptive text continued text another_func_name : Descriptive text func_name1, func_name2, :meth:`func_name`, func_name3 cjj|}|st|d|jd}|r|jdn|jd}|||j fS)zMatch ':role:`name`' or 'name'. is not a item namerrRname2) _func_rgxmatchrIgroupend)textmrrRrs r parse_item_namez7NumpyDocString._parse_see_also..parse_item_name6sg$$T*A D6)>776?D&*1776?0@Dquuw& &rNrTtrailingzGUnexpected comma or period after function list at index %d of line "%s"Fry allfuncsr,r$r) r _line_rgxrrr{rrrrfilterrI) rritemsrrestr2 line_match descriptionfuncsrrRr match_ends ` r _parse_see_alsozNumpyDocString._parse_see_also+s ' ?D::<--d3JK(..v6 ##J/K(($'1~~j'A4&HI#)%4??3#7 DJJL)!'' 3::<,;D,A)D$ LL$. +113DQ3#ABx~~/F4+78 eT]+ D6)>; ?< rcd}i}|jd}t|dkDr ||djdd|d<|D]B}|jd}t|dkDs#||djd||d<D|S) zT .. index: default :refguide: something, else, and more cH|Dcgc]}|jc}Scc}wrr )lstss r strip_each_inz2NumpyDocString._parse_index..strip_each_infs'*+!AGGI+ ++sz::r$rrdefault:r)rr.)rrrrr'r2s r _parse_indexzNumpyDocString._parse_index`s  ,--% wz(NumpyDocString._parse..sFa1<<>Fsrz The section z appears twice)rZr`rarb)r[r\r^r_r]T)rrrhrc)rmrrrr ValueErrorrrrBgetr{rrr)rrprr section_names has_returns has_yieldsmsgs r rrzNumpyDocString._parses  ++-.9AB%5WgB B=0 . :ICS/ !jM9ICS/ !"* ( Wg%%d+F7==3EF((7+88G$((<y)OP&& $ 6 6w ?W PP $ 6 6D!7!:W ##L1 $ 1 1'7 CW J&#'#7#7#@Z 'W % (Cs E)ct|dr6 tj|j}|d|jd|dz}|r t |t |y#t$rd}Y >C  ? Jrcg}||jz }||jz }||jz }dD]}||j|z }||j dz }||j |z }dD]}||j |z }dD]}||j|z }||j z }dj|S)N)rZr[r\r]r`r^r_re)rdrfrg)rarbr)rrrrrrrrB)rrr' param_listrs r rPzNumpyDocString.__str__"s t""$$ t  "" t))++B 4J 4'' 3 3C 4 t  ,, t!!),,4 (A 4$$Q' 'C (3 4J 4'' 3 3C 4 t  yy~rN)F)Tr)r%)*rCrDrErFrprrr}rrrrrrr_role _funcbacktick _funcplain _funcnamer _funcnamenext _descriptionrrrrrrrrrrr{rrrrrrrrrrPrGrr rVrVs> RB4 B b  2  "  B "  B b 2 B  B b!" B#$ %H**, &) '& H !  2J E>M/Ju },t3j@4GI%%fj9M!))&*=MEL 7Y.78I    ! !$1 14: :     I3j&D,#(J (     @$rrVcld|z|S|jd}djfd|DS)Nrrc3(K|] }|z ywrrG)rr indent_strs r rzindent..9s3Z!^3s)rrB)strrlinesrs @r rr4s9VJ { IIdOE 993U3 33rchtjdj|jdS)z"Deindent a list of lines maximallyr)rkrlrBr)rs r rr<s% ??499U+ , 2 24 88rc0|dz|t|zzdzSrjr)rstyles r rrAs $;s4y (4 //rc2eZdZddifdZdZfdZxZS) FunctionDocrNc$||_||_|&| tdtj|xsd}t j ||||dsB|?|j\}} ttj|}||}||d<yyy#ttf$rVtjddk\rtj|}ntj|}tj|}YrwxYw#t $r|d}YwxYw)NzNo function or docstring givenr%rWrz())_frrrgetdocrVrget_funcr signatureAttributeErrorsys version_infogetfullargspec getargspec formatargspecr)rrrrrs func_namer#argspecs r rzFunctionDoc.__init__Fs" ;| !ABB..&,"Cc62K T%5"mmoOD) -@ #G$5$5d$; ")"4"4T": ' 5 5w ?I @ -(k,  -s1*BC>A"C;8C>:C;;C>>DDct|jd|jj}t j |jr/t|jd|jj }||fS|j}||fS)NrC__call__)getattrr  __class__rCrisclassr)rr*rs r r"zFunctionDoc.get_funcaskDGGZ1H1HI ??477 #477J0@0@ADY77DYrc&d}|j\}}ddd}|jrL|j|vrtd|j|d|j|jdd|dz }|t||j z }|S) Nr%functionmethod)rmethzWarning: invalid role z.. z:: z )r)r"rprintrsuperrP)rr'rr*rolesr/s r rPzFunctionDoc.__str__is--/i#!# ::zz&.tzzl;< S4::r233ykL LC uw44 r)rCrDrErr"rP __classcell__)r/s@r rrEs"(d2*6rrcHeZdZdgZddeifdZedZedZdZ y)ClassDocr-Nr%c Ztj|s|td|||_dtj vrddlm}n t}|jdd|_ |r|jds|dz }||_ |"| tdtj|}tj!|||jd g}||urd}|jd g}|jd dr||urd } d |j"fd|j$ffD]y\} } || r g} t'| D]Y} | |vs|r| |vr tjt)|j| }| j+t-| d| |[| || <{yyy#t.$rYqwxYw)Nz"Expected a class or None, but got sphinxr)ALLshow_inherited_class_membersTrz&No class or documentation string givenmemberszexclude-membersshow_class_membersc*|sgS|jSr) splitlines)rs r splitlines_xz'ClassDoc.__init__..splitlines_xsI<<>)rrbrar%)rr0r_clsr%modulessphinx.ext.autodocr=objectrshow_inherited_membersendswith_modpydocr!rVrmethods propertiessortedr.rrQr$)rclsr modulenamefunc_docrsr=_members_excluderCfieldrdoc_listrRdoc_items r rzClassDoc.__init__~ss#A#IJ J s{{ " .(C&,jj2D':# j11#6 # J ;{ !IJJ,,s#Cc*::i, s?H::/4 ::*D 1hc6I * #,T\\!:".!@!B + uE{!H &u ! H,!)d(.B$!',||GDIIt4L'MH$OO )$L4J KM !#+DK + 7J 1$ .! !sA F F*)F*c|jgStj|jDcgc]G\}}|jdr||jvr#t |t r|j|r|Ic}}Scc}}wN_)rDr getmembersrextra_public_methodsrr_is_show_memberrrRrs r rLzClassDoc.methodssu 99 I'.'9'9$))'D5t- 9 99"42,,T2 5 55sA Bc |jgStj|jDcgc]P\}}|jds:|%t |t stj |r|j|r|Rc}}Scc}}wrX)rDrrZrrpropertyisdatadescriptorr\r]s r rMzClassDoc.propertiessy 99 I'.'9'9$))'D5t,\Zh%?--d3,,T2 5 55sAB cP|jry||jjvryy)NTF)rHrD__dict__)rrRs r r\zClassDoc._is_show_members&  & & tyy)) )r) rCrDrEr[rrr_rLrMr\rGrr r:r:zsG&< $k2+h5555rr:r r )rFrrkrrKwarningsr collectionsrcollections.abcrrrnr%r r ExceptionrIrQrVrrrrr:rGrr rgs8 "-  I.I.X {$< = iWiX 49 02.2jQ~Qr