o $a] @sdZddlZddlZddlZddlmZddlmZmZm Z m Z m Z m Z m Z ddlmZddlmZddlmZddlmZmZdd lmZdd lmZdd lmZeeZ e!d Z"e!d Z#e!dZ$e!dZ%e!dZ&e!dZ'e!dZ(e!dZ)e!dZ*e!dZ+e!dZ,dZ-ifde.de e.e.fde.fddZ/GdddZ0de 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,e0Z6dS).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)AnyCallableDictListTupleTypeUnion)SphinxConfig) 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].*$)NoneTrueFalseEllipsis_type translationsreturncCs$||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@seZdZdZedejZ   ddee e e fde de de d e d e d e d dfd dZd e fddZd e e fddZdded e e fddZd e e fddZd e e fddZddeded ee e e e ffdd Z  ddeded!ed e ee e e e ffd"d#Zd ee e e ffd$d%Zdd&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/d0Zdd1e e d2ed e e fd3d4Zd e d e fd5d6Z d7e e d e e fd8d9Z!d:e d1e e d e e fd;d<Z"dd=e d1e e d>e d e e fd?d@Z# BddCe ee e e e fdDe dEe d e e fdFdGZ$dHe dIe dJe e d e e fdKdLZ%dMe dCe ee e e e fd e e fdNdOZ&ddQed efdRdSZ'dTe d efdUdVZ(d1e e d efdWdXZ)d1e e d efdYdZZ*dd1e e d\ed e e fd]d^Z+ddTe ded efd_d`Z,d1e e d efdadbZ-d efdcddZ.d efdedfZ/ddgdhZ0ddidjZ1d:e dke d e e fdldmZ2d e e fdndoZ3dke d e e fdpdqZ4dke d e e fdrdsZ5dke d e e fdtduZ6dke d e e fdvdwZ7dke d e e fdxdyZ8dke d e e fdzd{Z9dke d|ed e e fd}d~Z:dke d e e fddZ;dke d e e fddZdke d e e fddZ?dke d e e fddZ@dke d e e fddZAdke d e e fddZBdke d e e fddZCdke d e e fddZDdke d e e fddZEdke d e e fddZFdTe d ee e e ffddZGde deHd e fddZId1e e d e e fddZJdHe d e fddZKdS)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 docstringconfigappwhatnameobjoptionsrc CsJ||_||_|jsddlm}|jr|jjn||_|s5t|r$d}nt|r,d}n t|r3d}nd}||_ ||_ ||_ ||_ t |trK|} n|} t| ddd |_g|_d |_d|_t|d sgg|_t|d sid |jd|jdt|jdd|jdt|jddt|jddt|jdd|jd|jdt|jddt|jdd|jd|jd|jdt|jdd|jd|jid|jd|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 classmodulefunctionobjectcSs|SN)rstrip)srrrz*GoogleDocstring.__init__..)modifierF_directive_sections _sectionsargs arguments attention attributescautiondangererrorexampleexampleshint importantz keyword argszkeyword argumentsmethodsnotenoteszother parameters parametersreceivereceivesrreturnsraiseraises referenceszsee alsotiptodowarningwarningswarnwarnsyieldyields)*_config_appsphinx.ext.napoleonr r!inspectisclassismodulecallable_what_name_obj_opt isinstancestr splitlinesr _line_iter _parsed_lines_is_in_section_section_indenthasattrr1_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)zReturn the parsed docstring in reStructuredText format. Returns ------- unicode Unicode version of the docstring.  )joinrurtrrr__str__s zGoogleDocstring.__str__cCs|jS)zReturn the parsed lines of the docstring in reStructuredText format. Returns ------- list(str) The lines of the docstring in a list. )r_ryrrrrus zGoogleDocstring.linesindentcCs\g}|j}|s,|r|||r,|t|j|j}|s,|r|||s|Sr+)r^peek_is_section_break _is_indentedappendnext)rtr|rulinerrr_consume_indented_blocks    z'GoogleDocstring._consume_indented_blockcCsPg}|jr&|jr&|s&|t|j|jr&|jr&|r|Sr+)r^has_nextr}_is_section_headerrrrtrurrr_consume_contiguouss  z#GoogleDocstring._consume_contiguouscCsHg}|j}|jr"|s"|t|j|j}|jr"|r|Sr+)r^r}rrrrtrurrrr_consume_emptys  zGoogleDocstring._consume_emptyTF parse_type prefer_typec Cst|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_regexmatchgroupstrip_escape_args_and_kwargsrPnapoleon_preprocess_typesrnapoleon_type_aliases _get_indent_dedentr __class__ru) rtrrrbeforecolonafterrXr_descrr|_descsrrr_consume_fields"       zGoogleDocstring._consume_fieldmultiplec Cs||g}|s<|||\}}}|r*|r*|dD] }||||fqn|s0|s0|r8||||f|r |S)N,)rr~rsplitrr) rtrrrfieldsrXrrr$rrr_consume_fieldss zGoogleDocstring._consume_fieldscCsbt|j}||\}}}|r|s||}}||7}|g||}|||j}||fSr+)rr^rr_consume_to_endrrPru)rtrrrrrrrr_consume_inline_attribute*s  z)GoogleDocstring._consume_inline_attributepreprocess_typesc Cs||}|rQ||d\}}}dd|}}}|r1|r)|g|dd}n|dd}|}|rB|rB|jjrBt||jjp@i}|||j}|||fgSgS)Nrrr{) r_consume_to_next_sectionrrPrrrrru) rtrrurrrrXrrrrr_consume_returns_section4s   z(GoogleDocstring._consume_returns_sectioncCs||}|Sr+)rrrrrr_consume_usage_sectionLsz&GoogleDocstring._consume_usage_sectioncCs*t|j}|d}||jvr|}|S)N:)rr^rlowerr2)rtsectionstripped_sectionrrr_consume_section_headerPs  z'GoogleDocstring._consume_section_headercCs,g}|jr|t|j|js|Sr+)r^rrrrrrrrWs   zGoogleDocstring._consume_to_endcCs8|g}|s|t|j|r ||Sr+)rr~rrr^rrrrr]s  z(GoogleDocstring._consume_to_next_sectionrufullcs.|r dd|DS||fdd|DS)NcSsg|]}|qSr)lstrip.0rrrr fsz+GoogleDocstring._dedent..csg|]}|dqSr+rr min_indentrrri)_get_min_indent)rtrurrrrrds zGoogleDocstring._dedentcCsl|drt|jddr|ddd}|dddkr$d|ddS|dd d kr4d |d dS|S) Nrstrip_signature_backslashFz\_rz**z\*\*r{*z\*)endswithgetattrrPrtr$rrrrksz'GoogleDocstring._escape_args_and_kwargsdesccCs|||r dg|}|S|ddr<|dd}||d}||}||kr0dg|}|Sd|dg||d}|S)Nrr::r{)_is_listrr_get_initial_indent_indent)rtr desc_blockr| block_indentrrr_fix_field_descvs      zGoogleDocstring._fix_field_desc admonitioncCsf||}t|dkrd||dfdgS|r-|||d}d|dg|dgSd|dgS)Nr{z .. %s:: %srrz.. %s::) _strip_emptylenrrr)rtrrurrr_format_admonitions   z"GoogleDocstring._format_admonitionprefixpaddingcCsr|r6|dur dt|}g}t|D]!\}}|dkr$|||q|r.|||q|dq|S|gS)N rr)r enumeraterr,)rtrrur result_linesirrrr _format_blocks  zGoogleDocstring._format_blockparamtyper field_role type_rolec Csg}|D]8\}}}||}t|r'||}d||f}||||n |d||f|r<|d|||fq|dgS)Nz:%s %s: z:%s %s:z :%s %s: %sr)ranyrextendrr) rtrrrrurXrrfieldrrr_format_docutils_paramss    z'GoogleDocstring._format_docutils_paramsrXrrcCs||}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 dS|g|S|gS) Nz -- r`z **%s** (%s)%sz**%s** (*%s*)%sz**%s**%sz%s%sz*%s*%srr{)rrr)rtrXrrhas_desc separatorrrrr _format_fields(    zGoogleDocstring._format_field field_typec Csd|}dt|}t|dk}g}|D]3\}}}||||} |r>|r2|||d| q|||d| q|||d| q|rU|drU|d|S)Nz:%s:rr{z * rr)rrrrrr) rtrrrmultirurXrrrrrr_format_fieldss     zGoogleDocstring._format_fieldsr peek_aheadcCsZ|j|d|}||jjkr+|r||S|d7}|j|d|}||jjksdS)Nr{r)r^r}sentinelr)rtrrrrr_get_current_indents   z#GoogleDocstring._get_current_indentrcCs*t|D] \}}|s|Sqt|Sr+)risspacer)rtrrr-rrrrs zGoogleDocstring._get_indentcCs |D] }|r ||SqdSNrrrrrrrs z#GoogleDocstring._get_initial_indentcCs>d}|D]}|r||}|dur|}q||kr|}q|pdSrr)rtrurrr|rrrrs zGoogleDocstring._get_min_indentrncsfdd|DS)Ncsg|]}d|qS)rrrrrrrrz+GoogleDocstring._indent..r)rtrurrrrrszGoogleDocstring._indentcCs2t|D]\}}||krdS|sdSqdS)NTF)rr)rtrr|rr-rrrrszGoogleDocstring._is_indentedcCs|sdSt|dr dSt|drdSt|dks#|ddr%dS||d}|}|ddD]}|rB||}||kSq4||kS)NFrTrrr{)_bullet_list_regexr_enumerated_list_regexrrr)rtrur| next_indentrrrrr s" zGoogleDocstring._is_listcCsz|j}t|}|r%|d|jvr%||}|jdd}||kS|j r;t |r;|j D] }| |r:dSq0dS)Nrr{)rTF) r^r}r_google_section_regexrrr2rrr1_directive_regex startswith)rtrr header_indentsection_indentdirective_sectionrrrrs      z"GoogleDocstring._is_section_headercCs8|j}|j p|p|jo|o|||j Sr+r^r}rrr`rra)rtrrrrr~(s  z!GoogleDocstring._is_section_breakcCs|jjdurP|jjD]G}t|tr|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) rPnapoleon_custom_sectionsr[r\_parse_custom_generic_sectionr2r"_parse_custom_params_style_section#_parse_custom_returns_style_sectionget)rtentryrrrrr0s     z%GoogleDocstring._load_custom_sectionscCs||_|jr'|jdvr'g}z|}Wn tyYnw|j|dS|jr| rbz*| }d|_ | |_ t|rJ|g|}n |j||}Wd|_ d|_ nd|_ d|_ w|jsn||}n|}|j||js,dSdS)N) attributedatapropertyTFr)rr_rXrW_parse_attribute_docstring StopIterationrr^rrrr`rrarrrr2rr)rtresrrurrrrsFs:        zGoogleDocstring._parsercCs|}|||Sr+)rr)rtrrrurrrrdhs z!GoogleDocstring._parse_admonitioncCs4|\}}|dd|}|r|dd|g|S)Nr :type: %s)rrr)rtrrrurrrrms z*GoogleDocstring._parse_attribute_docstringcCsg}|D]q\}}}|s||}|jjr6|||j}d|}|||||r5|d||fq|d||j rJd|j vrJ|d|d| dd|}|| |d|rr|d|| d|gd|dq|jjr|d|S) Nz :ivar %s: z:vartype %s: %sz.. attribute:: noindex :noindex:rrr) r_lookup_annotationrPnapoleon_use_ivar _qualify_namerYrrrrZrr)rtrrurXrrrrrrrrets0      z)GoogleDocstring._parse_attributes_sectioncCs6tdtdd}|jj}|||}|||S)NExampleExamples)r:r;)rrP$napoleon_use_admonition_for_examplesrr_parse_generic_section)rtrlabelsuse_admonitionlabelrrrrfs  z'GoogleDocstring._parse_examples_sectioncCs ||dS)NF)r rtrrrrr z-GoogleDocstring._parse_custom_generic_sectioncCs|||Sr+)rrrrrrrsz2GoogleDocstring._parse_custom_params_style_sectioncCs|jdd}|||S)NTr)rrrtrrrrrrs  z3GoogleDocstring._parse_custom_returns_style_sectioncCs6ddg}ddg}|}||d}|||dgS)Nz.. rubric:: Usage:rz.. code-block:: pythonr)rr)rtrheaderblockrurrr_parse_usage_sections  z$GoogleDocstring._parse_usage_sectionr cCsX||}||}|rd|}||d}nd|}|r(|dg|dgS|dgS)Nz.. admonition:: %srz.. rubric:: %sr)rrrr)rtrr rurrrrr s z&GoogleDocstring._parse_generic_sectioncCs0|}|jjr|j|dddS|td|S)Nkeywordkwtype)rrzKeyword Arguments)rrPnapoleon_use_keywordrrrrrrrrgsz0GoogleDocstring._parse_keyword_arguments_sectioncCsng}|jddD],\}}}|d||jr!d|jvr!|d|r/|dg||d|dq|S)NF)rz.. method:: %srrrr)rrrZrr)rtrrurXrrrrrrhs  z&GoogleDocstring._parse_methods_sectioncC|jj}|td|S)NNotes)rP!napoleon_use_admonition_for_notesr rrtrr rrrriz$GoogleDocstring._parse_notes_sectioncC6|jjr|jdd}||S|}|td|S)NTrzOther ParametersrPnapoleon_use_paramrrrrrrrrrj   z/GoogleDocstring._parse_other_parameters_sectioncCr)NTr Parametersrrrrrrcr!z)GoogleDocstring._parse_parameters_sectionc Cs|jddd}g}|D]M\}}}|j|}|r#|dr#|d}nt|r5|d}||dd}|r;d|nd }||}t|rMdd |nd } | d || fq |r`| d |S) NFT)rrr$rr{rrrz z :raises%s:%s) r _name_rgxrr _xref_regexfindrrrxr) rtrrrurXrrmposrrrrrms       z%GoogleDocstring._parse_raises_sectioncCr)NTrReceivesrrrrrrkr!z'GoogleDocstring._parse_receives_sectioncCr)N References)rP&napoleon_use_admonition_for_referencesr rrrrrrnrz)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|dgq|rg|drg|d|S) Nr{Frz * z :returns: * z :returns: z :rtype: %sr)rrrPnapoleon_use_rtyperrrr) rtrrr use_rtyperurXrrrrrrrls*   z&GoogleDocstring._parse_returns_sectioncCs |d|SNseealso)rdrrrrros z'GoogleDocstring._parse_see_also_sectioncCs|td|S)NWarns)rrrrrrrrp sz$GoogleDocstring._parse_warns_sectioncCs|jdd}|td|S)NTrYields)rrrrrrrrq#s z%GoogleDocstring._parse_yields_sectionc Csg}g}d}d}tt|D]A\}}|r||qt|}|ddkrK|rKd}|||}||d||||dq||qd| |d| fS)NrFrrT) r_xref_or_code_regexrr_single_colon_regexsearchstartendrxr) rtr before_colon after_colonr found_colonrsourcer&rrrr's$     z)GoogleDocstring._partition_field_on_colon attr_nameklasscCsV|r)d|vr)|dr|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)Nrrr{)rreversedranger)rtrur4rrr5rrrrHs&zGoogleDocstring._strip_emptycCst|jjr8|jdvr8|jr8t|ds,t|jdi}|t|jdip"it|jd||_||jvr8t |j|SdS)N)r(r' exception _annotationsautodoc_type_aliasesrr) rPnapoleon_attr_annotationsrWrYrbrupdaterrEr)rtrXlocalnsrrrr[s  z"GoogleDocstring._lookup_annotationNNrrNN)r{TF)TFFFr+)rr)r)r)rN)Lr@ __module__r>__doc__recompileXr#r r\r SphinxConfigr rrvrzruintrrrboolrrrrrrrrrrrrrrrrrrrrrrrrrr~rrrsrdrrerfrrrrr rgrhrirjrcrmrkrnrlrorprqrrrrrrrrrrFs> L             $  "     "        rtokenscs2t|}dfddfdd}t||S)Noptionaldefaultc3sd}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_bracesprevious_tokentoken)keywordsrr takewhile_setos<     z,_recombine_set_tokens..takewhile_setc3sR z|}Wn tyYdSw|dkr%|dd|Vn|Vq)NTrZr)r\r]r^rx)rUra)rcrr combine_sets   z*_recombine_set_tokens..combine_set) collectionsdequelist)rU token_queuerdr)rbrcr_recombine_set_tokensks   $ rispeccs(ddtfddt|D}|S)NcSs2t|r|dd}|dd}|d|gS|gS)Nr)_default_regexr)itemrXotherrrr postprocesss    z(_tokenize_type_spec..postprocessc3s&|]}|D]}|r|VqqdSr+r)r raw_tokenrnrprr s z&_tokenize_type_spec..)rg _token_regexr)rjrUrrrr_tokenize_type_specs  ruralocationcCsFdd}|ds|drd}|S||s4|dr |ds4|dr*|ds4|dr8|dr8d }|S|drKtjtd ||d d }|S|dr^tjtd ||d d }|S|dsh|drvtjtd ||d d }|S|ds|drtjtd||d d }|S|dvrd}|St|rd}|Sd}|S)NcSs$zt|WdStyYdSw)NFT)complex ValueError)rarrr is_numerics   z_token_type..is_numericr delimiterrZr["'literalz-invalid value set (missing closing brace): %srvz-invalid value set (missing opening brace): %sz4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %srVcontrol referencer%)rrloggerrJrr$r)rarvrytype_rrr _token_typesx -&    rcspddt|}t|}fdd|D}ddfddddd dd dd 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%rdefault_translation translationrrr convert_objs z-_convert_numpy_type_spec..convert_objcsg|] }|t|fqSr)r)rrar~rrrs z,_convert_numpy_type_spec..cSd|S)Nz``%s``rxrrrr. r/z*_convert_numpy_type_spec..cs |dS)Nrrr)rrrrr. s cSr)Nz*%s*rrrrrr. r/cS|Sr+rrrrrr.cSrr+rrrrrr.r)r}r%rrzrrc3s"|] \}}||VqdSr+)r)rrar) convertersrrrss z+_convert_numpy_type_spec..)rurirx)rrvrrUcombined_tokenstypes convertedr)rrrvrr_convert_numpy_type_specs  rcs eZdZdZ   d'deeeefdedededed e d e d dffd d Z d efddZ ded effdd Z d(de de d eeeeeffddZd)de d eeeeeeffddZd efddZd e fddZd e fdd Zd!ed eefd"d#Zd$eed eefd%d&ZZS)*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::)r1superrv)rtr r!r"r#r$r%r&rrrrvtszNumpyDocstring.__init__cCsnz|jdur t|jnd}Wn tyd}Ynw|j}|dur(|dur(dS|dur.d}d|d|gS)Nrrzdocstring of %s)rYrSgetfile TypeErrorrXrx)rtfilepathr$rrr _get_locationzs zNumpyDocstring._get_locationcs6tjd|vrdfdd|dDS|S)NrYc3s|]}|VqdSr+r)rrfuncrrrssz9NumpyDocstring._escape_args_and_kwargs..)rrrxrrrrrrsz&NumpyDocstring._escape_args_and_kwargsTFrrc Cst|j}|r||\}}}n|d}}||}}||}|r,|s,||}|r5|s5||}}|jjrFt|| |jj pCid}| |d}| | |}|||j}|||fS)Nr)rvrr{)rr^rrrrrPrrrrrrrrru) rtrrrrXrrr|rrrrrs(       zNumpyDocstring._consume_fieldrcCs |jddS)NT)r)r)rtrrrrrrz'NumpyDocstring._consume_returns_sectioncCs"t|j}t|st|j|Sr+)rr^rrrrrrrs   z&NumpyDocstring._consume_section_headercCsN|jd\}}|j p&|p&ddg||gkp&|jo&|o&|||j S)Nrrr)rtline1line2rrrr~s z NumpyDocstring._is_section_breakcCsj|jd\}}|}||jvrt|trtt|S|j r3t |r3|j D] }| |r2dSq(dS)NrTF) r^r}rr2r[r\rT_numpy_section_regexrr1rr)rtr underlinerrrrrs   z!NumpyDocstring._is_section_headerrcCs4|}z||WSty|d|YSwr-)r _parse_numpydoc_see_also_sectionrxr)rtrrurrrros   z&NumpyDocstring._parse_see_also_sectioncontentcsgdtdtttfffdd dtdttddffdd }fd d d}g}|D]x}|s4q-j|}|rq||dd rq||||d|||d}}|d d d g}|dspg}q-|ds|||d}d|vr|dD] }|r||gqq-|r|}q-|dur| |q-|||sgSfddDg}d} D]=\} } } | rd| | f} nd| } | s| r|dg7}|| g7}n |dd| 7<| r| d | g7}d} qd} 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 textrcsLj|}|r |}|ddur|ddfS|d|dfStd|)zMatch ':role:`name`' or 'name'r{Nrrz%s is not a item name)r#rgroupsrx)rr&gryrrparse_item_names    zHNumpyDocstring._parse_numpydoc_see_also_section..parse_item_namer$restNcs6|sdS|\}}|t||f|dd=dSr+)rrg)r$rrole)itemsrrr push_items  zBNumpyDocstring._parse_numpydoc_see_also_section..push_itemcsnjj}|dus |s|||fS|||}j|}|s"|||fS|}|d}|dp1|d}|||fS)Nrr$name2)rPrrr#r groupdict)r descriptionrr translatedrrnew_funcryrr translates      zBNumpyDocstring._parse_numpydoc_see_also_section..translaterr{rrrcsg|] \}}}|||qSrr)rrrr)rrrr"s zCNumpyDocstring._parse_numpydoc_see_also_section..Tz:%s:`%s`rrrz, %sFr.) r\rrrr#rr5rrrrrxr)rtrr current_funcrrr&rru last_had_descr$rrlinkr)rrrtrrrsl    "         z/NumpyDocstring._parse_numpydoc_see_also_sectionrJrKrL)r@rMr>rNr r\rrRr rrvrrrTrrrrr~rror __classcell__rrrrrs>\     "rr+)7rNrerSrO functoolsrtypingrrrrrrr sphinx.applicationr sphinx.configr rRsphinx.ext.napoleon.iteratorsr sphinx.localerr sphinx.utilrsphinx.util.inspectrsphinx.util.typingr getLoggerr@rrPrrrrr2r1r$rrrtrmrr\rrrirurdictrrrrrrsb  $             " +8 ;$