K iY dZddlZddlZddlZddlZddlmZddlmZddl m Z m Z ddl Z ddl Z dZGddZGd d eZed gd ZGd de ZdZGddeZGddeZGddeZddZy)z=Extract reference documentation from the NumPy source tree. N)warn) namedtuple)CallableMappingc|r,|djs|d=|r|djs|r,|djs|d=|r|djs|S)z.is_emptyWszz|# #r)r+r3)rr7s r read_to_next_empty_linezReader.read_to_next_empty_lineTs& %%' $%%h//rc*d}|j|S)Ncp|jxr%t|jt|k(Sr)r r.lstripr6s r is_unindentedz:Reader.read_to_next_unindented_line..is_unindented]s'JJLFc$++-&8CI&E Gr)r3)rr<s r read_to_next_unindented_linez#Reader.read_to_next_unindented_line\s H%%m44rcr|j|zt|jkr||j|zSyNr%r-rs r peekz Reader.peekas0 77Q;TYY '! $ $rcVdj|jj Sr?)joinrr r"s r r7zReader.is_emptygs!77499%++---rN)r)__name__ __module__ __qualname____doc__rrrr(r+r&r3r8r=r@r7rr rrs> )05  .rrceZdZdZy) ParseErrorc^|jd}t|dr|d|j}|S)Nr docstring in )argshasattrrK)rmessages r __str__zParseError.__str__ls,))A, 4 %$+T^^Z(d?Z)d@Z*dGdAZ+y)HNumpyDocStringzParses a numpydoc string to an abstract representation Instances define a mapping from section title to structured data. Signaturer%SummaryExtended Summary ParametersReturnsYieldsReceivesRaisesWarnsOther Parameters AttributesMethodsSee AlsoNotesWarnings ReferencesExamplesindexNc |}tj|jd}t||_t j |j|_ |jy#t$r }||_ d}~wwxYw)Nr) textwrapdedentrr_doccopydeepcopysections _parsed_data_parserIrK)rrKconfigorig_docstringes r rzNumpyDocString.__init__si"OOI.44T: 9%  MM$--8  KKM (AK  sA-- B6A>>Bc |j|Sr)rp)rkeys r rzNumpyDocString.__getitem__s  %%rcl||jvr|jd|zdy||j|<y)NzUnknown section %sFerror)rp_error_location)rrvvals r __setitem__zNumpyDocString.__setitem__s9 d'' '  !5!;5 I%(D  c "rc,t|jSr)iterrpr"s r __iter__zNumpyDocString.__iter__sD%%&&rc,t|jSr)r.rpr"s r __len__zNumpyDocString.__len__s4$$%%rc|jj|jjry|jjj }|j dry|jjdj }t |dk\rot|dhdhfvr^t |t |k7rGdj|jjdd d z}|jd |d |d |d|j dt |zxs|j dt |zS)NF .. index::Tr$-=rz...z'potentially wrong underline length... z z in rx) rlr+r&r@r startswithr.setrBrrz)rl1l2snips r _is_at_sectionzNumpyDocString._is_at_sections **, 99==? YY^^  # # % == & YY^^A  $ $ & r7a ! @}}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%)rlr8rr&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$r)rlr&rr rr. StopIterationr)rrrRs r _read_sectionszNumpyDocString._read_sectionss))--/--/D7==?Dt$DHn$TQ##DKKQR111))--/s B"B'%B'ct|}t|}g}|js|jj }d|vr7|j dd\}}|j |j }}n |rd|}}n|d}}|j }t|}t|}|jt||||js|S)Nz :r$)maxsplitr%) dedent_linesrr&r(r rr=r appendrQ) rcontentsingle_element_is_typerparamsheaderarg_namearg_typerTs r _parse_param_listz NumpyDocString._parse_param_listsw' 7O%%'VVX^^%Fv~%+\\$\%C"(%-^^%5x~~7G())+VhH)/hH113D%D$T*D MM)Hh= >%%'" rz:(?P(py:)?\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[,\.])?rc t|}g} fd}g}|D]g jsjj }d}|rK|j d}|j dr)|r'j d|j d fzd|s1 jdr |j j|rg}|j d } |jsnP||\} } } |j| | f|| dj}|r|d d k(r|d dj}attd|g}|j||fTj d j|S)z func_name : Descriptive text continued text another_func_name : Descriptive text func_name1, func_name2, :meth:`func_name`, func_name3 cjj|}|sjd|jd}|r|jdn|jd}|||j fS)zMatch ':role:`name`' or 'name'.Error parsing See Also entry rrRname2) _func_rgxmatchrzgroupend)textmrrRr2rs r parse_item_namez7NumpyDocString._parse_see_also..parse_item_name-sj$$T*A$$'DTH%MN776?D&*1776?0@Dquuw& &rNrTtrailingzGUnexpected comma or period after function list at index %d of line "%s"Frx allfuncsr,r$r) rr _line_rgxrrrzrrrrfilter) rritemsrrest line_match descriptionfuncsrrRr match_endr2s ` @r _parse_see_alsozNumpyDocString._parse_see_also sw' ' OD::<--d3JK(..v6 ##J/K(($'1~~j'A4&HI#)%4??3#7 DJJL)!'' 3::<,;D,A)D$ LL$. +113DQ3#ABx~~/F4+78 eT]+$$'DTH%MN; O< 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_in]s'*+!AGGI+ ++sz::r$rrdefault:r)rr.)rrrrr'r2s r _parse_indexzNumpyDocString._parse_indexWs  ,--% wz(NumpyDocString._parse..sFa1<<>Fsrz The section z appears twice in r)rZr`rarb)r[r\r^r_r]T)rrrhrc)rlrrrrr ValueErrorrrrBgetrzrrrr)rrorr section_names has_returns has_yieldsmsgs r rqzNumpyDocString._parses  ++-.XF)9'WFG =0 . :ICS/ !jM9ICS/ !"* ( Wg%%d+F7==3EF((7+88G$((,3TYYtyy~~5N*PQ&& $ 6 6w ?W PP $ 6 6D!7!:W ##L1 $ 1 1'7 CW J&#'#7#7#@Z 'W ' (Gs F cdt|dr |jSt|dr |jSy)N_cls_f)rNrrr"s r _objzNumpyDocString._objs, 4 99  T4 77Nrc|jI tj|j}|d|jjz }||rd|dndz }|r t |t |y#t$rd}YOwxYw)Nz in the docstring of rL.r%)rinspect getsourcefile TypeErrorrCrr)rrryfilenames r rzzNumpyDocString._error_locations 99  "00; *499+=+=*>? ?C T(1%r 9C S/ ! I  sA// A=<A=c"|t||zgSr)r.)rrRsymbols r _str_headerzNumpyDocString._str_headersc$i&''rc8|Dcgc] }d|z|z c}Scc}w)NrrG)rrindentr2s r _str_indentzNumpyDocString._str_indents.12dF T!222scF|dr|djddgdgzSdgS)NrW*z\*r%)replacer"s r _str_signaturezNumpyDocString._str_signatures3  %--c59:bTA At rc"|dr |ddgzSgS)NrXr%rGr"s r _str_summaryzNumpyDocString._str_summarys  ? ?bT) ) rc"|dr |ddgzSgS)NrYr%rGr"s r _str_extended_summaryz$NumpyDocString._str_extended_summarys# " #*+rd2 2 rcg}||r||j|z }||D]}g}|jr|j|j|jr|j|j|dj |gz }|j sudj |j j s||j|j z }|dgz }|S)Nz : r%)rrRrrSrBrTr r)rrRr'parampartss r _str_param_listzNumpyDocString._str_param_lists : 4##D) )Cd 8::LL,::LL, 5)**::"''%**"5";";"=4++EJJ77C 8 B4KC rcXg}||r"||j|z }|||z }|dgz }|Sr?)r)rrRr's r _str_sectionzNumpyDocString._str_sectionsA : 4##D) )C 4: C B4KC rc|dsgSg}||jdz }|dgz }d}|dD]\}}t|tsJg}|D]3\}}|r d|d|d} n|r d|d|d} nd|z} |j| 5dj |} || gz }|r'||j d j |gz }d}d }||j |j gz }|r|dgz }|dgz }|S) Nrcr%Trz:``z`%s`_, rF)rrrrrBrempty_description) r func_roler' last_had_descrrTlinksfuncrlinks r _str_see_alsozNumpyDocString._str_see_alsos0JI t ++ t   + BKE4eT* **E# # d)-t4D)2D9D"T>D T" #99U#D D6MCt''$(899 $ % t'')?)?(@AA% B(  B4KC t  rc|d}g}d}|jdd}|rd}|d|zgz }|jD](\}}|dk(r d}|d|dd j|gz }*|r|Sy) NrhFrr%Tz .. index:: %sz :z: r)rrrB)ridxr' output_index default_indexr referencess r _str_indexzNumpyDocString._str_index s7m  2. L -/00#&99; E GZ)#L GTYYz-BCD DC  E 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)rrrrrrr rB)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~rr)F)T)r))r%),rCrDrErFrorrr|rrrrrrr_role _funcbacktick _funcplain _funcnamer _funcnamenext _descriptionrrrrrrrrrqpropertyrrzrrrrrrrrr rPrGrr rVrVvsM RB4 B b  2  "  B "  B b 2 B  B b!" B#$ %H* &) '&H$ !  2N %E>M/Ju },t3j@4GI%%fj9M!))&*=MEL 7Y.78I    ! !$1 14: :     I5n&D,$(L  (3    @"rrVchtjdj|jdS)z"Deindent a list of lines maximallyr)rjrkrBr)liness r rr.s% ??499U+ , 2 24 88rc,eZdZddZdZfdZxZS) FunctionDocc||_||_|&| tdtj|xsd}|i}t j |||y)NzNo function or docstring givenr%)rrrrgetdocrVr)rrrrrrs r rzFunctionDoc.__init__4sU ;| !ABB..&,"C >Fc62rct|jd|jj}t j |jr/t|jd|jj }||fS|j}||fS)NrC__call__)getattrr __class__rCrisclassr)r func_namers r get_funczFunctionDoc.get_func@skDGGZ1H1HI ??477 #477J0@0@ADY77DYrc&d}|j\}}ddd}|jrL|j|vrtd|jz|d|j|jdd|dz }|t||j z }|S) Nr%functionmethod)rmethzWarning: invalid role %sz.. z:: z )r)r#rprintrsuperrP)rr'rr"rolesr s r rPzFunctionDoc.__str__Hs--/i#!# ::zz&04::=> UYYtzz2-F-68 8C uw44 r)rNN)rCrDrErr#rP __classcell__)r s@r rr3s 3rrceZdZddZy)ObjDocNcJ||_|i}tj|||y)Nrr)rrVr)robjrrrs r rzObjDoc.__init__[s( >Fc&9r)NN)rCrDrErrGrr r-r-Zs:rr-cHeZdZdgZddedfdZedZedZdZ y)ClassDocrNr%c btj|s|td|z||_dtj vrddlm}n t}|i}|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 %rsphinxr)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%)rr!rrsysmodulessphinx.ext.autodocr5objectrshow_inherited_membersendswith_modpydocrrVrmethods propertiessortedrrrQAttributeError)rclsr modulenamefunc_docrrr5_members_excluder;fieldrdoc_listrRdoc_items r rzClassDoc.__init__fss#CcIJ J s{{ " .(C >F&,jj *D'2# 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$ .! !s A F"" F.-F.c|jgStj|jDcgc]G\}}|jdr||jvr#t |t r|j|r|Ic}}Scc}}wN_)rr getmembersrextra_public_methodsrr_is_show_memberrrRrs r rDzClassDoc.methodssu 99 I'.'9'9$))'D1t-T666tX.((. 1 11sA Bc |jgStj|jDcgc]P\}}|jds:|%t |t stj |r|j|r|Rc}}Scc}}wrQ)rrrSrrrisdatadescriptorrUrVs r rEzClassDoc.propertiessy 99 I'.'9'9$))'D1t,\Zh%?--d3((. 1 11sAB cP|jry||jjvryy)NTF)r@r__dict__)rrRs r rUzClassDoc._is_show_members&  & & tyy)) )r) rCrDrErTrrrrDrErUrGrr r2r2bsG&< $k4+l1111rr2c6|Etj|rd}n-tj|rd}nt|trd}nd}|i}|dk(rt |t ||S|dvrt |||S|tj|}t|||S) Nclassmoduler%r?)rJrrr)r%r&)rrrr/) rr!ismodulerrr2rrCrr-)r0whatrrrs r get_doc_objectr`s | ??3 D   c "D X &DD ~ wks6JJ ' '3C77 ;,,s#Cc3v..r)NNN)rFrrjrrCwarningsr collectionsrcollections.abcrrrmr<r r ExceptionrIrQrVrrr-r2r`rGrr res "-  J.J.Z {$< = uWup 9 $.$N:^:S~Sl/r