c< ddlZddlZddlZddlZddlmZddlZddlmZddl m Z ddl Z ddl m Z ddlmZmZmZmZddlmZd ZGd d eZGd d eeZGddeeZGddeeZddZdS)N)Callable)FileSystemLoader)SandboxedEnvironment)BuiltinTemplateLoader)NumpyDocString FunctionDocClassDocObjDoc) make_xrefz1\b(import +matplotlib|from +matplotlib +import)\bceZdZddZdZddZdZddZd Zd Z d Z dd Z dZ dZ d dZdZdZfdZdZdZdZdZd!dZxZS)"SphinxDocStringNcf|i}tj|||||dS)Nconfig)r__init__ load_config)self docstringrs 9lib/python3.11/site-packages/numpydoc/docscrape_sphinx.pyrzSphinxDocString.__init__sA  Fi????      c|dd|_|dd|_|dd|_|dd|_|dt |_|dt|_|d d|_ |j ~tj tj td g}t|}t!| }|d |_ dSdS) N use_plotsFclass_members_toctreeTattributes_as_param_listxref_param_type xref_aliases xref_ignoretemplate templatesloadernumpydoc_docstring.rst)getrrrrdictrsetrrospathjoindirname__file__rr get_template)rr template_dirstemplate_loader template_envs rrzSphinxDocString.load_configsK77%+ZZ0G%N%N"(. 3Mt(T(T%%zz*;UCC"JJ~tvv>>!::mSUU;; :t44 = PW\\"'//(*C*C[QQRM.}==O/GGGL(556NOODMMM  P Pr`cd|zdgS)N .. rubric:: )rnamesymbols r _str_headerzSphinxDocString._str_header*s%r**rcd|zdzgS)N:r4rr5s r_str_field_listzSphinxDocString._str_field_list-sd S !!rc,g}|D]}|d|z|zgz }|S)N r4)rdocindentoutlines r _str_indentzSphinxDocString._str_indent0s3 ) )D C&L4'( (CC rcdgS)Nr3r4rs r_str_signaturezSphinxDocString._str_signature6s t rc|ddgzS)NSummaryr3r4rEs r _str_summaryzSphinxDocString._str_summary9sI"%%rc|ddgzS)NzExtended Summaryr3r4rEs r_str_extended_summaryz%SphinxDocString._str_extended_summary<s&'2$..rReturnsc.d}d}g}||r|||z }|dgz }||D]}|j}|r"|jrt||j|j}|jr6||||j|fzgz }n.||||zgz }|j s||dgdz }n|||j dz }|dgz }|S)Nz **%s** : %sz%sr3..) r;typerr rrr5rCstripdesc)rr5 named_fmt unnamed_fmtrAparam param_types r _str_returnszSphinxDocString._str_returns?sU!   :  4''-- -C B4KCd  "Z $"6!*"D$5t7G""J:P4++"ej&6&6&8&8*%EEFCC4++[:;K;K;M;M-M,NOOOCz;4++TFA666CC4++EJ:::Ct  rcr|dddkr d|ddzS|dddkr d|ddzS|S)N**z\*\*r*z\*r4r:s r_escape_args_and_kwargsz'SphinxDocString._escape_args_and_kwargsZsV 8t  T!""X% % "1"X_ 48# #KrcD||}d|d}|s||fSt|j|d}t |s?t |t s*tj|stj |sd}tj |}|r|s||fSt|dd}|r|d}nd}d|d||d}|rtj d |d d }tjd d | } | r(| d }n|dd }| d}||fS)aDetermine how to display a parameter Emulates autosummary behavior if fake_autosummary Parameters ---------- param : str The name of the parameter desc : list of str The parameter description as given in the docstring. This is ignored when autosummary logic applies. fake_autosummary : bool If True, autosummary-style behaviour will apply for params that are attributes of the class and have a docstring. Returns ------- display_param : str The marked up parameter name for display. This may include a link to the corresponding attribute's own documentation. desc : list of str A list of description lines. This may be identical to the input ``desc``, if ``autosum is None`` or ``param`` is not a class attribute, or it will be a summary of the class attribute's docstring. Notes ----- This does not have the autosummary functionality to display a method's signature, and hence is not used to format methods. It may be complicated to incorporate autosummary's signature mangling, as it relies on Sphinx's plugin mechanism. rZN_namer3.z:obj:`z `z\n\s*\nrrz^([A-Z].*?\.)(?:\s|$)r> )r\rQgetattr_objcallable isinstancepropertyinspectisgetsetdescriptorismemberdescriptorpydocgetdocresplitsearchr)group partition) rrUrRfake_autosummary display_param param_objobj_docprefix link_prefixms r_process_paramzSphinxDocString._process_parambsD,,U[[]];; 'U  ' $& &DIud33 Y   )X.. ))44 ))44   I,y)) 'g ' $& &w++  #,,,KKKA@@+@u@@@  $8J ;;A>D 2CHHTZZ\\4J4JKKA /wwqzz''))~~d++A.::d##Dd""rFcg}||r|||z }|dgz }||D]}||j|j|\}}g}|r|||j}|r>|j}|jrt||j|j }|||| d |gz }|sdg}|| |dz }|dgz }|S)aIGenerate RST for a listing of parameters or similar Parameter names are displayed as bold text, and descriptions are in definition lists. Parameters ---------- name : str Section name (e.g. Parameters) fake_autosummary : bool When True, the parameter names may correspond to attributes of the object beign documented, usually ``property`` instances on a class. In this case, names will be linked to fuller descriptions. Returns ------- rst : list of str r3z : rNrO) r;rwr5rRappendrPrr rrrCr)) rr5rprArUrqrRpartsrVs r_str_param_listzSphinxDocString._str_param_listsE& :  4''-- -C B4KCd  &*&9&9J ,<''# t 0LL///"Z -!&J+%.&(94;K&& LL,,,t''E):):(;<<<" 6Dt''a000t  rcg}||r|d|dgz }t|dd}|rd|d}g}g}||D]}||j}t|j|jd}t |s+t |tstj |sd}|r%tj |r|d||jgz }| ||r|d gz }|j r|d gz }|dg|zz }|rtd td |D}d |zdzdz} d|fz} |dd| gz }|D]v}d|jzdz}dd|jD} |jr d|jd| } || || fzgz }w|| gz }|dgz }|S)zp Generate a member listing, autosummary:: table where possible, and a table where not. r2r3r^~r_)r5N z.. autosummary::z :toctree:c3DK|]}t|jdzVdS)r<N)lenr5).0ps r z3SphinxDocString._str_member_list.. s.%F%F!c!&kkAo%F%F%F%F%F%Fr=z z ==========z %%%ds %%s rZr>c3>K|]}|VdSN)rQ)rxs rrz3SphinxDocString._str_member_list..s*#B#B!AGGII#B#B#B#B#B#Br(z) )ra_replacer5rQrbrcrdrerfisdatadescriptorrirjryrmaxr)rRrP) rr5rArtautosumothersrUrrmaxlen_0hdrfmtrRs r_str_member_listz SphinxDocString._str_member_lists|  :-  )4))2. .CT7B//F '&VGFd ) )EJ,<,<,>,>??$DIuz4@@ Y''%!)X66%/ ::% !%I)i!8!8) :f :ej : :;;GGMM%(((( &*++-,N++Ctg~% q#%F%Fv%F%F%F"F"FGGHnt+h6${2B}$#00E%*"2"2"4"44t;D88#B#Buz#B#B#BBBHHJJDz875:7777C4,.//CCu  B4KC rcg}||rc|||z }tjd||d}||z }|dgz }|S)Nr`r3)r7textwrapdedentr)rl)rr5rAcontents r _str_sectionzSphinxDocString._str_sectionsq :  4##D)) )CodiiT &;&;<<BB4HHG 7NC B4KC rcg}|drEt|}ddg}|||ddz }|S)NzSee Alsoz .. seealso::r3rY)super _str_see_alsorC)r func_rolerAsee_also __class__s rrzSphinxDocString._str_see_also s[   2ww,,Y77H!2&C 4##HQRRL11 1C rcjg}|dr(ddg}|||dz }|dgz }|S)NWarningsz .. warning::r3)rC)rrAs r _str_warningszSphinxDocString._str_warnings(sK   !2&C 4##D$455 5C B4KC rcP|d}g}t|dkr|S|d|ddgz }|D]N\}}|dkr |dkr|dd|gz }/|d |d d |gz }O|dgz }|S) Nindexrz .. index:: defaultr3refguidez single: , r~z: ,)rr$itemsr))ridxrAsection referencess r _str_indexzSphinxDocString._str_index0s7m s88q= J 6cggi446677#&99;; A A GZ)# AJ& A=dii &;&;==>>?g??*)=)=??@@ t  rcg}|dr||dz }t|dtr |dg|d<||d|dgz }|ddgz }g}|dD]L}t jd|tj}|r(||dM|dd d|Dzdgz }|S) N Referencesr3z.. only:: latexz.. \[([a-z0-9._-]+)\]rr~rcg|]}d|d S)[z]_r4)ritems r z3SphinxDocString._str_references..Qs &F&F&F|4|||&F&F&Fr) r7rdstrextendrkmatchIryrnr))rrArrBrvs r_str_referenceszSphinxDocString._str_referencesAs   M 4##L11 1C$|,c22 :&*<&8%9\" JJtL) * * * B4KC %r* *CE\* - -H5tRTBB-LL,,, EDII&F&F&F&F&FGGGL LC rc:d|d}|jretjt|rKd|vrGg}||dz }|ddgz }|||dz }|dgz }|S|dS)Nr`Exampleszplot::z .. plot::r3)r)rrkrmIMPORT_MATPLOTLIB_REr7rCr)r examples_strrAs r _str_exampleszSphinxDocString._str_examplesTsyyj!122  N 1 . == 1 , 1 C 4##J// /C K$ $C 4##D$455 5C B4KCJ$$Z00 0rrobjc&id|d|d|d|d|dd|dd |d d |d d |dd|dd|dd|d||d|dd| d| d|j r|ddn| dd| di}d| D}|jjd!i|}d ||d |S)"N signaturersummaryextended_summary parameters ParametersreturnsrLyieldsYieldsreceivesReceivesother_parameterszOther ParametersraisesRaiseswarnsWarnswarningsrnotesNotesrexamples attributes AttributesT)rpmethodsMethodsc@i|]\}}|d|S)r`)r))rkvs r z+SphinxDocString.__str__..|s( 5 5 5$!Qa1 5 5 5rr`r4)rFrrIrKr{rWrrrrrrrrrrenderr)rCrl)rr@rnsrendereds r__str__zSphinxDocString.__str__esX ,,.. T__&&  t((**   : : < <  $..|<<  t((33   d''11  ))*55   4 45G H H  d''11  T&&w//  **,,  **955  T&&w//  $..00 **,,! " ,5$..|d.SSS&&|44' ( t,,Y77)  ,6 5"((** 5 5 5'4='--"--yy))(..*>*>GGHHHrr)r0)r<)rL)F)rr)__name__ __module__ __qualname__rrr7r;rCrFrIrKrWr\rwr{rrrrrrrr __classcell__)rs@rrrs!!!! P P P++++""" &&&///6L#L#L#\....`555n"&111"IIIIIIIIrrceZdZddZdS)SphinxFunctionDocNch|i}||tj||||dSNr?r)rr rrrr?rs rrzSphinxFunctionDoc.__init__sC  F    T3C??????rNNrrrrr4rrrrs.@@@@@@rrceZdZddZdS)SphinxClassDocNcj|i}||tj|||d|dS)N)r?func_docr)rr r)rrr?rrs rrzSphinxClassDoc.__init__sE  F    $tFKKKKKKr)NNNrr4rrrrs.LLLLLLrrceZdZddZdS) SphinxObjDocNch|i}||tj||||dSr)rr rrs rrzSphinxObjDoc.__init__sB  F    cs6::::::rrrr4rrrrs(;;;;;;rrc|Htj|rd}n1tj|rd}nt|trd}nd}|i}t jt jtdg}|&t}| ||nt|}t|}|d|d <|dkrt|t || S|d vrt!||| S|t#j|}t'||| S)Nclassmodulefunctionobjectr )dirsr!r#r)rr?r)rmethodrr)rfisclassismodulerdrr'r(r)r*r+rinitrrr,rrrirjr)rwhatr?rbuilderr-r.r/s rget_doc_objectrsf  ?3   DD  c " " DD X & & DDD W\\"'//(";";[IIJM:/11W=9999*=99'???L%223KLLF: w5c,=3vVVVV ' '5 #f====  $,s##CCV4444r)NNNN)rkrfrricollections.abcrr'jinja2rjinja2.sandboxrsphinxsphinx.jinja2gluer docscraperr r r xrefr rrrrrrr4rrrs  $$$$$$ ######////// 333333DDDDDDDDDDDDLkIkIkIkIkInkIkIkI\ @@@@@@@@LLLLL_hLLL;;;;;?F;;;555555r