o ×$•a]¾ã @sÌdZddlZddlZddlZddlmZddlmZmZm Z m Z m Z m Z m Z ddlmZddlmZddlmZddlmZmZdd lmZdd lmZdd lmZe e¡Z e !d ¡Z"e !d ¡Z#e !d¡Z$e !d¡Z%e !d¡Z&e !d¡Z'e !d¡Z(e !d¡Z)e !d¡Z*e !d¡Z+e !d¡Z,dZ-ifde.de e.e.fde.fdd„Z/Gdd„dƒZ0de e.de e.fd d!„Z1d"e.de e.fd#d$„Z2d-d%e.d&e.de.fd'd(„Z3difde.d&e.de4de.fd)d*„Z5Gd+d,„d,e0ƒZ6dS).zì sphinx.ext.napoleon.docstring ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Classes for docstring parsing and formatting. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. éN)Úpartial)ÚAnyÚCallableÚDictÚListÚTupleÚTypeÚUnion)ÚSphinx©ÚConfig)Ú modify_iter)Ú_Ú__)Úlogging)Ústringify_annotation)Úget_type_hintsz \.\. \S+::z^(\s|\w)+:\s*$z(.+?)\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z (?((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|(?:``.+?``))z5(?:(?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:)?`.+?`)z^(\*|\+|\-)(\s+\S|\s*$)zP^(?P\()?(\d+|#|[ivxlcdm]+|[IVXLCDM]+|[a-zA-Z])(?(paren)\)|\.)(\s+\S|\s*$)z_(,\sor\s|\sor\s|\sof\s|:\s|\sto\s|,\sand\s|\sand\s|,\s|[{]|[}]|"(?:\\"|[^"])*"|'(?:\\'|[^'])*')z^default[^_0-9A-Za-z].*$)ÚNoneÚTrueÚFalseÚEllipsisÚ_typeÚ translationsÚreturncCs$||vr||S|dkrdSd|S)z0Convert type specification to reference in reST.rz :obj:`None`ú :class:`%s`©)rrrrú?/usr/lib/python3/dist-packages/sphinx/ext/napoleon/docstring.pyÚ_convert_type_spec9s rc@s¤eZdZdZe dej¡Z   d¡dee e e fde de de d e d e d e d dfd d„Zd e fdd„Zd e e fdd„Zd¢ded e e fdd„Zd e e fdd„Zd e e fdd„Zd£deded ee e e e ffdd „Z  d¤deded!ed e ee e e e ffd"d#„Zd ee e e ffd$d%„Zd¥d&ed e ee e e e ffd'd(„Zd e e fd)d*„Zd e fd+d,„Zd e e fd-d.„Zd e e fd/d0„Zd¥d1e e d2ed e e fd3d4„Zd e d e fd5d6„Z d7e e d e e fd8d9„Z!d:e d1e e d e e fd;d<„Z"d¦d=e d1e e d>e d e e fd?d@„Z# Bd§dCe ee e e e fdDe dEe d e e fdFdG„Z$dHe dIe dJe e d e e fdKdL„Z%dMe dCe ee e e e fd e e fdNdO„Z&d¨dQed efdRdS„Z'dTe d efdUdV„Z(d1e e d efdWdX„Z)d1e e d efdYdZ„Z*d©d1e e d\ed e e fd]d^„Z+d¢dTe ded efd_d`„Z,d1e e d efdadb„Z-d efdcdd„Z.d efdedf„Z/dªdgdh„Z0dªdidj„Z1d:e dke d e e fdldm„Z2d e e fdndo„Z3dke d e e fdpdq„Z4dke d e e fdrds„Z5dke d e e fdtdu„Z6dke d e e fdvdw„Z7dke d e e fdxdy„Z8dke d e e fdzd{„Z9dke d|ed e e fd}d~„Z:dke d e e fdd€„Z;dke d e e fdd‚„Zdke d e e fd‡dˆ„Z?dke d e e fd‰dŠ„Z@dke d e e fd‹dŒ„ZAdke d e e fddŽ„ZBdke d e e fdd„ZCdke d e e fd‘d’„ZDdke d e e fd“d”„ZEdke d e e fd•d–„ZFdTe d ee e e ffd—d˜„ZGd™e dšeHd e fd›dœ„ZId1e e d e e fddž„ZJdHe d e fdŸd „ZKdS)«ÚGoogleDocstringaVConvert Google style docstrings to reStructuredText. Parameters ---------- docstring : :obj:`str` or :obj:`list` of :obj:`str` The docstring to parse, given either as a string or split into individual lines. config: :obj:`sphinx.ext.napoleon.Config` or :obj:`sphinx.config.Config` The configuration settings to use. If not given, defaults to the config object on `app`; or if `app` is not given defaults to the a new :class:`sphinx.ext.napoleon.Config` object. Other Parameters ---------------- app : :class:`sphinx.application.Sphinx`, optional Application object representing the Sphinx process. what : :obj:`str`, optional A string specifying the type of the object to which the docstring belongs. Valid values: "module", "class", "exception", "function", "method", "attribute". name : :obj:`str`, optional The fully qualified name of the object. obj : module, class, exception, function, method, or attribute The object to which the docstring belongs. options : :class:`sphinx.ext.autodoc.Options`, optional The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are True if the flag option of same name was given to the auto directive. Example ------- >>> from sphinx.ext.napoleon import Config >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True) >>> docstring = '''One line summary. ... ... Extended description. ... ... Args: ... arg1(int): Description of `arg1` ... arg2(str): Description of `arg2` ... Returns: ... str: Description of return value. ... ''' >>> print(GoogleDocstring(docstring, config)) One line summary. Extended description. :param arg1: Description of `arg1` :type arg1: int :param arg2: Description of `arg2` :type arg2: str :returns: Description of return value. :rtype: str zX^\s*((?::(?P\S+):)?`(?P~?[a-zA-Z0-9_.-]+)`| (?P~?[a-zA-Z0-9_.-]+))\s*NÚÚ docstringÚconfigÚappÚwhatÚnameÚobjÚoptionsrc CsJ||_||_|jsddlm}|jr|jjn|ƒ|_|s5t |¡r$d}nt |¡r,d}n t|ƒr3d}nd}||_ ||_ ||_ ||_ t |tƒrK| ¡} n|} t| dd„d |_g|_d |_d|_t|d ƒsgg|_t|d ƒsid |j“d|j“dt|jdƒ“d|j“dt|jdƒ“dt|jdƒ“dt|jdƒ“d|j“d|j“dt|jdƒ“dt|jdƒ“d|j“d|j“d|j“dt|jdƒ“d|j“d|j“id|j“d|j “d |j “d!|j!“d"|j!“d#|j"“d$|j"“d%|j#“d&|j$“d't|jd'ƒ“d(t|jd(ƒ“d)t|jd)ƒ“d*t|jd)ƒ“d+|j%“d,|j%“d-|j&“d.|j&“¥|_'| (¡| )¡dS)/Nrr ÚclassÚmoduleÚfunctionÚobjectcSs| ¡S©N)Úrstrip)ÚsrrrÚ¤óz*GoogleDocstring.__init__..)ÚmodifierFÚ_directive_sectionsÚ _sectionsÚargsÚ argumentsÚ attentionÚ attributesÚcautionÚdangerÚerrorÚexampleÚexamplesÚhintÚ importantz keyword argszkeyword argumentsÚmethodsÚnoteÚnoteszother parametersÚ parametersÚreceiveÚreceivesrÚreturnsÚraiseÚraisesÚ referenceszsee alsoÚtipÚtodoÚwarningÚwarningsÚwarnÚwarnsÚyieldÚyields)*Ú_configÚ_appÚsphinx.ext.napoleonr r!ÚinspectÚisclassÚismoduleÚcallableÚ_whatÚ_nameÚ_objÚ_optÚ isinstanceÚstrÚ splitlinesr Ú _line_iterÚ _parsed_linesÚ_is_in_sectionÚ_section_indentÚhasattrr1Ú_parse_parameters_sectionrÚ_parse_admonitionÚ_parse_attributes_sectionÚ_parse_examples_sectionÚ _parse_keyword_arguments_sectionÚ_parse_methods_sectionÚ_parse_notes_sectionÚ_parse_other_parameters_sectionÚ_parse_receives_sectionÚ_parse_returns_sectionÚ_parse_raises_sectionÚ_parse_references_sectionÚ_parse_see_also_sectionÚ_parse_warns_sectionÚ_parse_yields_sectionr2Ú_load_custom_sectionsÚ_parse) Úselfr r!r"r#r$r%r&r ÚlinesrrrÚ__init__ˆsÄ       ÿþ ýü û ú ùø ÷ ö õ ô óò ñðïîíìëêéèçæ å ä ã âá à!ß"Þ% zGoogleDocstring.__init__cCsd | ¡¡S)z Return the parsed docstring in reStructuredText format. Returns ------- unicode Unicode version of the docstring. Ú )Újoinru©rtrrrÚ__str__Ôs zGoogleDocstring.__str__cCs|jS)z³Return the parsed lines of the docstring in reStructuredText format. Returns ------- list(str) The lines of the docstring in a list. )r_ryrrrrußs zGoogleDocstring.lineséÚindentcCs\g}|j ¡}| ¡s,|r| ||¡r,| t|jƒ¡|j ¡}| ¡s,|r| ||¡s|Sr+)r^ÚpeekÚ_is_section_breakÚ _is_indentedÚappendÚnext)rtr|ruÚlinerrrÚ_consume_indented_blockês ÿ ÿ ýÿ ÿz'GoogleDocstring._consume_indented_blockcCsPg}|j ¡r&|j ¡r&| ¡s&| t|jƒ¡|j ¡r&|j ¡r&| ¡r|Sr+)r^Úhas_nextr}Ú_is_section_headerr€r©rtrurrrÚ_consume_contiguousós ÿþ ýÿþz#GoogleDocstring._consume_contiguouscCsHg}|j ¡}|j ¡r"|s"| t|jƒ¡|j ¡}|j ¡r"|r|Sr+)r^r}r„r€r©rtrur‚rrrÚ_consume_emptyûs  þzGoogleDocstring._consume_emptyTFÚ parse_typeÚ prefer_typec CsÎt|jƒ}| |¡\}}}|d|}}} |r*t |¡} | r*|  d¡ ¡}|  d¡}| |¡}|r8|s8||}}|rG|jj rGt ||jj pEiƒ}|  |¡d} | g|  | | ¡¡} | | |j¡ ¡} ||| fS)Nrr{é)rr^Ú_partition_field_on_colonÚ_google_typed_arg_regexÚmatchÚgroupÚstripÚ_escape_args_and_kwargsrPÚnapoleon_preprocess_typesrÚnapoleon_type_aliasesÚ _get_indentÚ_dedentrƒÚ __class__ru) rtrŠr‹r‚ÚbeforeÚcolonÚafterrXrÚ_descrr|Ú_descsrrrÚ_consume_fields"       zGoogleDocstring._consume_fieldÚmultiplec Cs|| ¡g}| ¡s<| ||¡\}}}|r*|r*| d¡D] }| | ¡||f¡qn|s0|s0|r8| |||f¡| ¡r |S)Nú,)r‰r~rÚsplitr€r‘) rtrŠr‹ržÚfieldsrXrr›r$rrrÚ_consume_fieldssÿ úzGoogleDocstring._consume_fieldscCsbt|jƒ}| |¡\}}}|r|s||}}||7}|g| | ¡¡}| ||j¡ ¡}||fSr+)rr^rr–Ú_consume_to_endr—rPru)rtr‚rr™r›rœrrrÚ_consume_inline_attribute*s  z)GoogleDocstring._consume_inline_attributeÚpreprocess_typesc Cs¦| | ¡¡}|rQ| |d¡\}}}dd|}}}|r1|r)|g|dd…}n|dd…}|}|rB|rB|jjrBt||jjp@iƒ}| ||j¡ ¡}|||fgSgS)Nrrr{) r–Ú_consume_to_next_sectionrrPr“rr”r—ru) rtr¥rur˜r™ršrXrr›rrrÚ_consume_returns_section4s  ÿ z(GoogleDocstring._consume_returns_sectioncCs| | ¡¡}|Sr+)r–r¦r†rrrÚ_consume_usage_sectionLsz&GoogleDocstring._consume_usage_sectioncCs*t|jƒ}| d¡}| ¡|jvr|}|S)Nú:)rr^r‘Úlowerr2)rtÚsectionÚstripped_sectionrrrÚ_consume_section_headerPs  z'GoogleDocstring._consume_section_headercCs,g}|j ¡r| t|jƒ¡|j ¡s|Sr+)r^r„r€rr†rrrr£Ws   ÿzGoogleDocstring._consume_to_endcCs8| ¡g}| ¡s| t|jƒ¡| ¡r || ¡Sr+)r‰r~r€rr^r†rrrr¦]s ÿ z(GoogleDocstring._consume_to_next_sectionruÚfullcs.|r dd„|DƒS| |¡‰‡fdd„|DƒS)NcSsg|]}| ¡‘qSr)Úlstrip©Ú.0r‚rrrÚ fsz+GoogleDocstring._dedent..csg|]}|ˆd…‘qSr+rr°©Ú min_indentrrr²ió)Ú_get_min_indent)rtrur®rr³rr–ds zGoogleDocstring._dedentcCsl| d¡rt|jddƒr|dd…d}|dd…dkr$d|dd…S|dd …d kr4d |d d…S|S) NrÚstrip_signature_backslashFéÿÿÿÿz\_rŒz**z\*\*r{Ú*z\*)ÚendswithÚgetattrrP©rtr$rrrr’ksz'GoogleDocstring._escape_args_and_kwargsÚdesccCs|| |¡r dg|}|S|d d¡r<|dd…}| |d¡}| |¡}||kr0dg|}|Sd|dg| |d¡}|S)Nrrú::r{é)Ú_is_listrºr•Ú_get_initial_indentÚ_indent)rtr½Ú desc_blockr|Ú block_indentrrrÚ_fix_field_descvs   ø   ÿzGoogleDocstring._fix_field_descÚ admonitioncCsf| |¡}t|ƒdkrd||d ¡fdgS|r-| | |¡d¡}d|dg|dgSd|dgS)Nr{z .. %s:: %srréz.. %s::)Ú _strip_emptyÚlenr‘rÂr–)rtrÆrurrrÚ_format_admonitionƒs   z"GoogleDocstring._format_admonitionÚprefixÚpaddingcCsr|r6|dur dt|ƒ}g}t|ƒD]!\}}|dkr$| || ¡¡q|r.| ||¡q| d¡q|S|gS)Nú rr)rÉÚ enumerater€r,)rtrËrurÌÚ result_linesÚir‚rrrÚ _format_blocks  zGoogleDocstring._format_blockÚparamÚtyper¡Ú field_roleÚ type_rolec Cs„g}|D]8\}}}| |¡}t|ƒr'| |¡}d||f}| | ||¡¡n | d||f¡|r<| d|||f¡q|dgS)Nz:%s %s: z:%s %s:z :%s %s: %sr)rÈÚanyrÅÚextendrÑr€) rtr¡rÔrÕrurXrr›ÚfieldrrrÚ_format_docutils_paramss   € z'GoogleDocstring._format_docutils_paramsrXrr›cCsÈ| |¡}t|ƒ}|r dnd}|r.|r'd|vrd|||f}n%d|||f}nd||f}n|rBd|vr;d||f}n d||f}nd}|ra| |¡}|d r\||d g|d d…S|g|S|gS) Nz -- rú`z **%s** (%s)%sz**%s** (*%s*)%sz**%s**%sz%s%sz*%s*%srr{)rÈrÖrÅ)rtrXrr›Úhas_descÚ separatorrØrrrÚ _format_field®s(    zGoogleDocstring._format_fieldÚ field_typec Cs®d| ¡}dt|ƒ}t|ƒdk}g}|D]3\}}}| |||¡} |r>|r2| | |d| ¡¡q| | |d| ¡¡q| | |d| ¡¡q|rU|drU| d¡|S)Nz:%s:rÍr{z * r¸r)r‘rÉrÝr×rÑr€) rtrÞr¡rÌÚmultirurXrr›rØrrrÚ_format_fieldsËs     zGoogleDocstring._format_fieldsrÚ peek_aheadcCsZ|j |d¡|}||jjkr+|r| |¡S|d7}|j |d¡|}||jjksdS)Nr{r)r^r}Úsentinelr•)rtrár‚rrrÚ_get_current_indentÞs   üz#GoogleDocstring._get_current_indentr‚cCs*t|ƒD] \}}| ¡s|Sqt|ƒSr+)rÎÚisspacerÉ)rtr‚rÐr-rrrr•çs ÿzGoogleDocstring._get_indentcCs |D] }|r | |¡SqdS©Nr©r•rˆrrrrÁís ÿz#GoogleDocstring._get_initial_indentcCs>d}|D]}|r| |¡}|dur|}q||kr|}q|pdSråræ)rtrur´r‚r|rrrr¶ós €zGoogleDocstring._get_min_indentr¿Úncs‡fdd„|DƒS)Ncsg|]}dˆ|‘qS)rÍrr°©rçrrr²ÿrµz+GoogleDocstring._indent..r)rtrurçrrèrrÂþszGoogleDocstring._indentcCs2t|ƒD]\}}||krdS| ¡sdSqdS)NTF)rÎrä)rtr‚r|rÐr-rrrrsÿzGoogleDocstring._is_indentedcCsŽ|sdSt |d¡r dSt |d¡rdSt|ƒdks#|d d¡r%dS| |d¡}|}|dd…D]}|rB| |¡}||kSq4||kS)NFrTrŒr¾r{)Ú_bullet_list_regexrÚ_enumerated_list_regexrÉrºr•)rtrur|Ú next_indentr‚rrrrÀ s" ýzGoogleDocstring._is_listcCsz|j ¡ ¡}t |¡}|r%| d¡|jvr%| |¡}|jdd}||kS|j r;t  |¡r;|j D] }|  |¡r:dSq0dS)Nr©r{)ráTF) r^r}rªÚ_google_section_regexrr‘r2r•rãr1Ú_directive_regexÚ startswith)rtr«rÚ header_indentÚsection_indentÚdirective_sectionrrrr…s      ÿz"GoogleDocstring._is_section_headercCs8|j ¡}|j ¡ p| ¡p|jo|o| ||j¡ Sr+©r^r}r„r…r`rra)rtr‚rrrr~(s  ÿÿüz!GoogleDocstring._is_section_breakcCs¨|jjdurP|jjD]G}t|tƒr|j|j| ¡<q |ddkr+|j|j|d ¡<q |ddkr<|j|j|d ¡<q |j  |d ¡|j¡|j|d ¡<q dSdS)Nr{Ú params_stylerÚ returns_style) rPÚnapoleon_custom_sectionsr[r\Ú_parse_custom_generic_sectionr2rªÚ"_parse_custom_params_style_sectionÚ#_parse_custom_returns_style_sectionÚget)rtÚentryrrrrr0s    ÿ ÿÿÿïz%GoogleDocstring._load_custom_sectionscCs| ¡|_|jr'|jdvr'g}z| ¡}Wn tyYnw|j |¡dS|j ¡r|  ¡rbz*|  ¡}d|_ |  ¡|_ t |¡rJ|g| ¡}n |j| ¡|ƒ}Wd|_ d|_ nd|_ d|_ w|jsn| ¡| ¡}n| ¡}|j |¡|j ¡s,dSdS)N)Ú attributeÚdataÚpropertyTFr)r‰r_rXrWÚ_parse_attribute_docstringÚ StopIterationr×r^r„r…r­r`rãrarírr¦r2rªr‡)rtÚresr«rurrrrsFs:   ÿ    €ÿ îzGoogleDocstring._parser«cCs| ¡}| ||¡Sr+)r¦rÊ)rtrÆr«rurrrrdhs z!GoogleDocstring._parse_admonitioncCs4| ¡\}}| dd|¡}|r| dd|g¡|S)Nrú :type: %s)r¤rÝr×)rtrr›rurrrrþms z*GoogleDocstring._parse_attribute_docstringcCsg}| ¡D]q\}}}|s| |¡}|jjr6| ||j¡}d|}| | ||¡¡|r5| d||f¡q| d|¡|j rJd|j vrJ| d¡| d¡|  dd|¡}| |  |d¡¡|rr| d¡| |  d|gd¡¡| d¡q|jjr| d¡|S) Nz :ivar %s: z:vartype %s: %sz.. attribute:: Únoindexú :noindex:rrÇr) r¢Ú_lookup_annotationrPÚnapoleon_use_ivarÚ _qualify_namerYr×rÑr€rZrÝrÂ)rtr«rurXrr›rØr¡rrrrets0 €     z)GoogleDocstring._parse_attributes_sectioncCs6tdƒtdƒdœ}|jj}| | ¡|¡}| ||¡S)NÚExampleÚExamples)r:r;)rrPÚ$napoleon_use_admonition_for_examplesrùrªÚ_parse_generic_section)rtr«ÚlabelsÚuse_admonitionÚlabelrrrrfs þ z'GoogleDocstring._parse_examples_sectioncCs | |d¡S)NF)r ©rtr«rrrrö˜ó z-GoogleDocstring._parse_custom_generic_sectioncCs| || ¡¡Sr+)ràr¢rrrrr÷œsz2GoogleDocstring._parse_custom_params_style_sectioncCs|jdd}| ||¡S)NT©r¥)r§rà©rtr«r¡rrrrøŸs  z3GoogleDocstring._parse_custom_returns_style_sectioncCs6ddg}ddg}| ¡}| |d¡}|||dgS)Nz.. rubric:: Usage:rz.. code-block:: pythonrÇ)r¨rÂ)rtr«ÚheaderÚblockrurrrÚ_parse_usage_section£s  z$GoogleDocstring._parse_usage_sectionr cCsX| | ¡¡}| |¡}|rd|}| |d¡}nd|}|r(|dg|dgS|dgS)Nz.. admonition:: %srÇz.. rubric:: %sr)rÈr¦r–rÂ)rtr«r rurrrrr ªs z&GoogleDocstring._parse_generic_sectioncCs0| ¡}|jjr|j|dddS| tdƒ|¡S)NÚkeywordÚkwtype)rÔrÕzKeyword Arguments)r¢rPÚnapoleon_use_keywordrÙràrrrrrrg·sýz0GoogleDocstring._parse_keyword_arguments_sectioncCsng}|jddD],\}}}| d|¡|jr!d|jvr!| d¡|r/| dg| |d¡¡| d¡q|S)NF)rŠz.. method:: %srrrrÇ)r¢r€rZr×rÂ)rtr«rurXrr›rrrrhÁs  z&GoogleDocstring._parse_methods_sectioncCó|jj}| tdƒ|¡S)NÚNotes)rPÚ!napoleon_use_admonition_for_notesr r©rtr«r rrrriÌóz$GoogleDocstring._parse_notes_sectioncCó6|jjr|jdd}| |¡S| ¡}| tdƒ|¡S)NT©ržzOther Parameters©rPÚnapoleon_use_paramr¢rÙràrrrrrrjÐó   z/GoogleDocstring._parse_other_parameters_sectioncCr)NTrÚ ParametersrrrrrrcÙr!z)GoogleDocstring._parse_parameters_sectionc CsÄ|jddd}g}|D]M\}}}|j |¡}|r#| d¡r#| d¡}nt |¡r5| d¡}||dd…}|r;d|nd }| |¡}t|ƒrMdd  |¡nd } |  d || f¡q |r`|  d ¡|S) NFT)rŠr‹r$rÚr{r¸rÍrz z :raises%s:%s) r¢Ú _name_rgxrrÚ _xref_regexÚfindrÈrÖrxr€) rtr«r¡rurXrr›ÚmÚposrœrrrrmâs       z%GoogleDocstring._parse_raises_sectioncCr)NTrÚReceivesrrrrrrkôr!z'GoogleDocstring._parse_receives_sectioncCr)NÚ References)rPÚ&napoleon_use_admonition_for_referencesr rrrrrrnýrz)GoogleDocstring._parse_references_sectionc CsÒ| ¡}t|ƒdk}|rd}n|jj}g}|D]D\}}}|r&| |d|¡} n| |||¡} |rE|r;| | d| ¡¡q| | d| ¡¡q| | d| ¡¡|r[|r[| d|dg¡q|rg|drg| d¡|S) Nr{Frz * z :returns: * z :returns: z :rtype: %sr¸)r§rÉrPÚnapoleon_use_rtyperÝr×rÑr€) rtr«r¡rßÚ use_rtyperurXrr›rØrrrrls* €  z&GoogleDocstring._parse_returns_sectioncCs | d|¡S©NÚseealso)rdrrrrros z'GoogleDocstring._parse_see_also_sectioncCs| tdƒ| ¡¡S)NÚWarns)ràrr¢rrrrrp sz$GoogleDocstring._parse_warns_sectioncCs|jdd}| tdƒ|¡S)NTrÚYields)r§ràrrrrrrq#s z%GoogleDocstring._parse_yields_sectionc CsÀg}g}d}d}tt |¡ƒD]A\}}|r| |¡qt |¡}|ddkrK|rKd}|| ¡| ¡…}| |d| ¡…¡| || ¡d…¡q| |¡qd |¡  ¡|d |¡  ¡fS)NrFrŒrT) rÎÚ_xref_or_code_regexr r€Ú_single_colon_regexÚsearchÚstartÚendrxr‘) rtr‚Ú before_colonÚ after_colonr™Ú found_colonrÐÚsourcer&rrrr's$     þz)GoogleDocstring._partition_field_on_colonÚ attr_nameÚklasscCsV|r)d|vr)| d¡r|dd…}z|j}Wn ty"|j}Ynwd||fS|S)NÚ.ú~r{z~%s.%s)rîÚ __qualname__ÚAttributeErrorÚ__name__)rtr:r;Úqrrrr=s      ÿ zGoogleDocstring._qualify_namecCsŒ|rDd}t|ƒD] \}}|r|}nq|dkrg}d}ttt|ƒƒƒD] }||}|r/|}nq#|dks<|dt|ƒkrD|||d…}|S)Nr¸rr{)rÎÚreversedÚrangerÉ)rtrur4rÐr‚r5rrrrÈHs&þþzGoogleDocstring._strip_emptycCst|jjr8|jdvr8|jr8t|dƒs,t|jdiƒ}| t|jdiƒp"i¡t|jd|ƒ|_||jvr8t |j|ƒSdS)N)r(r'Ú exceptionÚ _annotationsÚautodoc_type_aliasesr”r) rPÚnapoleon_attr_annotationsrWrYrbr»ÚupdaterrEr)rtrXÚlocalnsrrrr[s ÿþ z"GoogleDocstring._lookup_annotation©NNrrNN)r{©TF)TFF©Fr+)rÒrÓ)r)r¿)rN)Lr@Ú __module__r>Ú__doc__ÚreÚcompileÚXr#r r\rÚ SphinxConfigr rrvrzruÚintrƒr‡r‰Úboolrrr¢r¤r§r¨r­r£r¦r–r’rÅrÊrÑrÙrÝràrãr•rÁr¶rÂrrÀr…r~rrrsrdrþrerfrör÷rørr rgrhrirjrcrmrkrnrlrorprqrrrrÈrrrrrrFsÂ>ÿþÿÿÿþþ þL     ÿ ÿÿ ÿ   ÿ   $ ÿÿÿ þ" ÿ    "        rÚtokenscs2t |¡}d‰‡fdd„‰‡fdd„}t||ƒƒS)N©ÚoptionalÚdefaultc3s¶d}d} z| ¡}Wn tyYdSw|dkr|}q| ¡s#q|ˆvr7| |¡|dur5| |¡dS|dur@|Vd}|dkrI|d7}n|dkrQ|d8}|V|dkrZdSq)NrTú, ú{r{ú})ÚpopleftÚ IndexErrorr‘Ú appendleft)rUÚ open_bracesÚprevious_tokenÚtoken)ÚkeywordsrrÚ takewhile_setos<€  ÿ   áz,_recombine_set_tokens..takewhile_setc3sR z| ¡}Wn tyYdSw|dkr%| d¡d ˆ|ƒ¡Vn|Vq)NTrZr)r\r]r^rx)rUra)rcrrÚ combine_set“s€  ÿ öz*_recombine_set_tokens..combine_set)Ú collectionsÚdequeÚlist)rUÚ token_queuerdr)rbrcrÚ_recombine_set_tokensks   $ riÚspeccs(dd„‰t‡fdd„t |¡Dƒƒ}|S)NcSs2t |¡r|dd…}|dd…}|d|gS|gS)NéérÍ)Ú_default_regexr)ÚitemrXÚotherrrrÚ postprocess¤s    z(_tokenize_type_spec..postprocessc3s&|]}ˆ|ƒD]}|r|VqqdSr+r)r±Ú raw_tokenrn©rprrÚ ¯s€ýü ÿz&_tokenize_type_spec..)rgÚ _token_regexr )rjrUrrrrÚ_tokenize_type_spec£s  þruraÚlocationcCsFdd„}| d¡s| d¡rd}|S||ƒs4| d¡r | d¡s4| d¡r*| d¡s4| d¡r8| d¡r8d }|S| d¡rKtjtd ƒ||d d }|S| d¡r^tjtd ƒ||d d }|S| d¡sh| d¡rvtjtd ƒ||d d }|S| d¡s€| d¡rŽtjtdƒ||d d }|S|dvr–d}|St |¡rŸd}|Sd}|S)NcSs$zt|ƒWdStyYdSw)NFT)ÚcomplexÚ ValueError)rarrrÚ is_numeric¹s   ýÿz_token_type..is_numericrÍÚ delimiterrZr[ú"ú'Úliteralz-invalid value set (missing closing brace): %s©rvz-invalid value set (missing opening brace): %sz4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %srVÚcontrolÚ referencer%)rîrºÚloggerrJrr$r)rarvryÚtype_rrrÚ _token_type¸sx -Õÿþþýýüü& Ûý âýéýðý ÷ ûþrƒcspdd„‰t|ƒ}t|ƒ}‡fdd„|Dƒ}dd„‡‡fdd„dd„d d„d d„d œ‰d  ‡fd d„|Dƒ¡}|S)NcSsP| ||¡}|tvr|dkrd}n |dkr|dkrd}t |¡dur&||}|S)Nrú :obj:`%s`z...z:obj:`%s `)rùÚ _SINGLETONSr$r)r%rÚdefault_translationÚ translationrrrÚ convert_objôs z-_convert_numpy_type_spec..convert_objcsg|] }|t|ˆƒf‘qSr)rƒ)r±rar~rrr²s ÿÿz,_convert_numpy_type_spec..cSód|S)Nz``%s``r©Úxrrrr. r/z*_convert_numpy_type_spec..cs ˆ|ˆdƒS)NrrrŠ)rˆrrrr. s cSr‰)Nz*%s*rrŠrrrr. r/cSó|Sr+rrŠrrrr.ócSrŒr+rrŠrrrr.r)r}r%rrzr€rc3s"|] \}}ˆ |¡|ƒVqdSr+)rù)r±rar‚)Ú convertersrrrss€ z+_convert_numpy_type_spec..)rurirx)rrvrrUÚcombined_tokensÚtypesÚ convertedr)rˆrŽrvrrÚ_convert_numpy_type_specós þ ûr’cs eZdZdZ   d'deeeefdedededed e d e d df‡fd d „ Z d efdd„Z ded ef‡fdd„ Z d(de de d eeeeeffdd„Zd)de d eeeeeeffdd„Zd efdd„Zd e fdd„Zd e fdd „Zd!ed eefd"d#„Zd$eed eefd%d&„Z‡ZS)*ÚNumpyDocstringaÑ Convert NumPy style docstrings to reStructuredText. Parameters ---------- docstring : :obj:`str` or :obj:`list` of :obj:`str` The docstring to parse, given either as a string or split into individual lines. config: :obj:`sphinx.ext.napoleon.Config` or :obj:`sphinx.config.Config` The configuration settings to use. If not given, defaults to the config object on `app`; or if `app` is not given defaults to the a new :class:`sphinx.ext.napoleon.Config` object. Other Parameters ---------------- app : :class:`sphinx.application.Sphinx`, optional Application object representing the Sphinx process. what : :obj:`str`, optional A string specifying the type of the object to which the docstring belongs. Valid values: "module", "class", "exception", "function", "method", "attribute". name : :obj:`str`, optional The fully qualified name of the object. obj : module, class, exception, function, method, or attribute The object to which the docstring belongs. options : :class:`sphinx.ext.autodoc.Options`, optional The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are True if the flag option of same name was given to the auto directive. Example ------- >>> from sphinx.ext.napoleon import Config >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True) >>> docstring = '''One line summary. ... ... Extended description. ... ... Parameters ... ---------- ... arg1 : int ... Description of `arg1` ... arg2 : str ... Description of `arg2` ... Returns ... ------- ... str ... Description of return value. ... ''' >>> print(NumpyDocstring(docstring, config)) One line summary. Extended description. :param arg1: Description of `arg1` :type arg1: int :param arg2: Description of `arg2` :type arg2: str :returns: Description of return value. :rtype: str Methods ------- __str__() Return the parsed docstring in reStructuredText format. Returns ------- str UTF-8 encoded version of the docstring. __unicode__() Return the parsed docstring in reStructuredText format. Returns ------- unicode Unicode version of the docstring. lines() Return the parsed lines of the docstring in reStructuredText format. Returns ------- list(str) The lines of the docstring in a list. Nrr r!r"r#r$r%r&rc s$dg|_tƒ |||||||¡dS)Nz .. index::)r1Úsuperrv)rtr r!r"r#r$r%r&©r—rrrvtszNumpyDocstring.__init__cCsnz|jdur t |j¡nd}Wn tyd}Ynw|j}|dur(|dur(dS|dur.d}d |d|g¡S)Nrr©zdocstring of %s)rYrSÚgetfileÚ TypeErrorrXrx)rtÚfilepathr$rrrÚ _get_locationzs ÿzNumpyDocstring._get_locationcs6tƒj‰d|vrd ‡fdd„| d¡Dƒ¡Sˆ|ƒS)NrYc3s|]}ˆ|ƒVqdSr+r)r±rÒ©ÚfuncrrrsŒs€z9NumpyDocstring._escape_args_and_kwargs..)r”r’rxr r¼r•ršrr’ˆsz&NumpyDocstring._escape_args_and_kwargsTFrŠr‹c CsÆt|jƒ}|r| |¡\}}}n|d}}| ¡| ¡}}| |¡}|r,|s,| |¡}|r5|s5||}}|jjrFt||  ¡|jj pCid}|  |¡d}|  |  |¡¡}| ||j¡ ¡}|||fS)Nr)rvrr{)rr^rr‘r’rrPr“r’r™r”r•r–rƒr—ru) rtrŠr‹r‚rXrrr|r›rrrrs(      ý zNumpyDocstring._consume_fieldr¥cCs |jddS)NT)r‹)r¢)rtr¥rrrr§¬rz'NumpyDocstring._consume_returns_sectioncCs"t|jƒ}t |¡st|jƒ|Sr+)rr^rírrrrrr­°s   z&NumpyDocstring._consume_section_headercCsN|j d¡\}}|j ¡ p&| ¡p&ddg||gkp&|jo&|o&| ||j¡ S)NrŒrrò)rtÚline1Úline2rrrr~·s ÿþÿûz NumpyDocstring._is_section_breakcCsj|j d¡\}}| ¡}||jvrt|tƒrtt |¡ƒS|j r3t  |¡r3|j D] }|  |¡r2dSq(dS)NrŒTF) r^r}rªr2r[r\rTÚ_numpy_section_regexrr1rírî)rtr«Ú underlinerñrrrr…Às   ÿz!NumpyDocstring._is_section_headerr«cCs4| ¡}z| |¡WSty| d|¡YSwr-)r¦Ú _parse_numpydoc_see_also_sectionrxrÊ)rtr«rurrrroÌs   ÿz&NumpyDocstring._parse_see_also_sectionÚcontentcsg‰dtdtttff‡fdd„ ‰dtdttddf‡‡fdd „ }‡fd d „‰d}g}|D]x}| ¡s4q-ˆj |¡}|rq|| ¡d… ¡ d ¡rq|||ƒ|d| ¡…|| ¡d…}}| d d ¡d  ¡g}|dspg}q-| d¡sš|||ƒd}d|vr“| d¡D] }| ¡r‘||gƒq†q-| ¡r™|}q-|dur¥|  | ¡¡q-|||ƒˆs¯gS‡fdd„ˆDƒ‰g}d} ˆD]=\} } } | rÌd| | f} nd| } | sÔ| rß|dg7}|| g7}n |dd| 7<| rù|ˆ  d  | ¡g¡7}d} q¾d} q¾|dg7}ˆ  d|¡S)a Derived from the NumpyDoc implementation of _parse_see_also. See Also -------- func_name : Descriptive text continued text another_func_name : Descriptive text func_name1, func_name2, :meth:`func_name`, func_name3 ÚtextrcsLˆj |¡}|r | ¡}|ddur|ddfS|d|dfStd|ƒ‚)zMatch ':role:`name`' or 'name'r{NrÇrŒz%s is not a item name)r#rÚgroupsrx)r¢r&ÚgryrrÚparse_item_nameás    zHNumpyDocstring._parse_numpydoc_see_also_section..parse_item_namer$ÚrestNcs6|sdSˆ|ƒ\}}ˆ |t|ƒ|f¡|dd…=dSr+)r€rg)r$r¦Úrole)Úitemsr¥rrÚ push_itemìs  zBNumpyDocstring._parse_numpydoc_see_also_section..push_itemcsnˆjj}|dus |s|||fS| ||¡}ˆj |¡}|s"|||fS| ¡}|d}|dp1|d}|||fS)Nr§r$Úname2)rPr”rùr#rÚ groupdict)r›Ú descriptionr§rÚ translatedrr£Únew_funcryrrÚ translateós      zBNumpyDocstring._parse_numpydoc_see_also_section..translater©r{rrÍrŸcsg|] \}}}ˆ|||ƒ‘qSrr)r±r›r¬r§)r¯rrr²"s ÿÿzCNumpyDocstring._parse_numpydoc_see_also_section..Tz:%s:`%s`r„rr¸z, %sFr.) r\rrr‘r#rr5rîr r€rÂrxrÊ)rtr¡r©Ú current_funcr¦r‚r&r›ruÚ last_had_descr$r½r§Úlinkr)r¨r¥rtr¯rr Ósl    "€   €þ€€  þ    z/NumpyDocstring._parse_numpydoc_see_also_sectionrJrKrL)r@rMr>rNr r\rrRr rrvr™r’rTrrr§r­r~r…ror Ú __classcell__rrr•rr“s>\þÿÿÿþþþ  ÿ ÿ  "r“r+)7rNrerSrOÚ functoolsrÚtypingrrrrrrr Úsphinx.applicationr Ú sphinx.configr rRÚsphinx.ext.napoleon.iteratorsr Ú sphinx.localerrÚ sphinx.utilrÚsphinx.util.inspectrÚsphinx.util.typingrÚ getLoggerr@rrPrírìrŽržr2r1r$rérêrtrmr…r\rrrirurƒÚdictr’r“rrrrÚsb  $            ÿÿ ÿÿÿ" +8 ;$