U
    \ªSh!½  ã                   @  sœ  d Z ddlmZ ddlZddlZddlZddlmZ ddlm	Z	m
Z
 ddlmZ ddlmZ ddlmZmZ dd	lmZ dd
lmZmZ e 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&dZ'G dd„ dej(ƒZ)i fddddœdd„Z*G dd„ dƒZ+d d d!œd"d#„Z,dd d$œd%d&„Z-d1dd'dd(œd)d*„Z.di fdd'd+dd,œd-d.„Z/G d/d0„ d0e+ƒZ0dS )2z-Classes for docstring parsing and formatting.é    )ÚannotationsN)Úpartial)ÚAnyÚCallable)ÚSphinx©ÚConfig)Ú_Ú__)Úlogging)Úget_type_hintsÚstringify_annotationz
\.\. \S+::z^(\s|\w)+:\s*$z(.+?)\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z(?<!:):(?!:)z>((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|(?:``.+?``))z5(?:(?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:)?`.+?`)z^(\*|\+|\-)(\s+\S|\s*$)zP^(?P<paren>\()?(\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ÚEllipsisc                      s<   e Zd ZdZeƒ Zdddœdd„Zddœ‡ fdd	„Z‡  ZS )
ÚDequez‡
    A subclass of deque that mimics ``pockets.iterators.modify_iter``.

    The `.Deque.get` and `.Deque.next` methods are added.
    Úintr   )ÚnÚreturnc                 C  s   |t | ƒk r| | S | jS )zx
        Return the nth element of the stack, or ``self.sentinel`` if n is
        greater than the stack size.
        )ÚlenÚsentinel)Úselfr   © r   úP/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/ext/napoleon/docstring.pyÚget8   s    z	Deque.get©r   c                   s   | rt ƒ  ¡ S t‚d S ©N)ÚsuperÚpopleftÚStopIteration©r   ©Ú	__class__r   r   Únext?   s    
z
Deque.next)	Ú__name__Ú
__module__Ú__qualname__Ú__doc__Úobjectr   r   r$   Ú__classcell__r   r   r"   r   r   /   s   r   Ústrzdict[str, str])Ú_typeÚtranslationsr   c                 C  s(   | |kr||  S | dkrdS d|  S | S )z0Convert type specification to reference in reST.r   z:obj:`None`ú:class:`%s`r   )r,   r-   r   r   r   Ú_convert_type_specF   s    r/   c                
   @  sÔ  e Zd ZdZe dej¡Zd£dddddd	d	d
dœdd„Zddœdd„Z	ddœdd„Z
d¤dddœdd„Zddœdd„Zddœdd„Zd¥ddd d!œd"d#„Zd¦dddd$d%œd&d'„Zd(dœd)d*„Zd§dd$d+œd,d-„Zddœd.d/„Zddœd0d1„Zddœd2d3„Zddœd4d5„Zd¨dddd6œd7d8„Zddd9œd:d;„Zddd<œd=d>„Zdddd?œd@dA„Zd©dddBddCœdDdE„Zdªd$ddddHœdIdJ„ZdddddKœdLdM„Zdd$ddNœdOdP„Zd«dddRœdSdT„ZdddUœdVdW„ZdddXœdYdZ„Z dddXœd[d\„Z!d¬dddd^œd_d`„Z"d­ddddaœdbdc„Z#dddXœddde„Z$ddœdfdg„Z%ddœdhdi„Z&d
dœdjdk„Z'd
dœdldm„Z(ddddnœdodp„Z)ddœdqdr„Z*dddsœdtdu„Z+dddsœdvdw„Z,dddsœdxdy„Z-dddsœdzd{„Z.dddsœd|d}„Z/dddsœd~d„Z0dddd€œdd‚„Z1dddsœdƒd„„Z2dddsœd…d†„Z3dddsœd‡dˆ„Z4dddsœd‰dŠ„Z5dddsœd‹dŒ„Z6dddsœddŽ„Z7dddsœdd„Z8dddsœd‘d’„Z9dddsœd“d”„Z:dddsœd•d–„Z;dddsœd—d˜„Z<dddsœd™dš„Z=dd›dUœdœd„Z>dddXœdždŸ„Z?ddd œd¡d¢„Z@dS )®ÚGoogleDocstringaV  Convert 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.
    <BLANKLINE>
    Extended description.
    <BLANKLINE>
    :param arg1: Description of `arg1`
    :type arg1: int
    :param arg2: Description of `arg2`
    :type arg2: str
    <BLANKLINE>
    :returns: Description of return value.
    :rtype: str
    <BLANKLINE>

    zX^\s*((?::(?P<role>\S+):)?`(?P<name>~?[a-zA-Z0-9_.-]+)`| (?P<name2>~?[a-zA-Z0-9_.-]+))\s*NÚ ústr | list[str]úSphinxConfig | NoneúSphinx | Noner+   r   r   ©Ú	docstringÚconfigÚappÚwhatÚnameÚobjÚoptionsr   c           
   #   C  sÀ  || _ || _| j s4ddlm} | jr,| jjn|ƒ | _ |sjt |¡rHd}n"t |¡rXd}nt|ƒrfd}nd}|| _	|| _
|| _|| _t|tƒr–| ¡ }	n|}	tttj|	ƒƒ| _g | _d| _d| _t| dƒsÎg | _t| d	ƒs¬| j| jt| jd
ƒ| jt| jdƒt| jdƒt| jdƒ| j| jt| jdƒt| jdƒ| j| j| jt| jdƒ| j | j!| j| j"| j"| j#| j#| j$| j$| j%| j&t| jdƒt| jdƒt| jdƒt| jdƒ| j'| j'| j(| j(dœ"| _)|  *¡  |  +¡  d S )Nr   r   ÚclassÚmoduleÚfunctionr)   FÚ_directive_sectionsÚ	_sectionsÚ	attentionÚcautionÚdangerÚerrorÚhintÚ	importantÚnoteÚtipÚtodoÚwarning)"ÚargsÚ	argumentsrB   Ú
attributesrC   rD   rE   ÚexampleÚexamplesrF   rG   zkeyword argszkeyword argumentsÚmethodsrH   Únoteszother parametersÚ
parametersZreceiveZreceivesr   ZreturnsÚraiseZraisesZ
referenceszsee alsorI   rJ   rK   ÚwarningsÚwarnZwarnsÚyieldZyields),Ú_configZ_appZsphinx.ext.napoleonr   r7   ÚinspectÚisclassÚismoduleÚcallableÚ_whatÚ_nameÚ_objÚ_optÚ
isinstancer+   Ú
splitlinesr   ÚmapÚrstripÚ_linesÚ_parsed_linesÚ_is_in_sectionÚ_section_indentÚhasattrr@   Ú_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_sectionrA   Ú_load_custom_sectionsÚ_parse)
r   r6   r7   r8   r9   r:   r;   r<   r   Úlinesr   r   r   Ú__init__•   s€    
















Þ%zGoogleDocstring.__init__r   c                 C  s   d  |  ¡ ¡S )z Return the parsed docstring in reStructuredText format.

        Returns
        -------
        unicode
            Unicode version of the docstring.

        Ú
)Újoinr{   r!   r   r   r   Ú__str__è   s    	zGoogleDocstring.__str__ú	list[str]c                 C  s   | j S )z³Return the parsed lines of the docstring in reStructuredText format.

        Returns
        -------
        list(str)
            The lines of the docstring in a list.

        )rf   r!   r   r   r   r{   ó   s    	zGoogleDocstring.linesé   r   )Úindentr   c                 C  sJ   g }| j  d¡}|  ¡ sF|r(|  ||¡rF| | j  ¡ ¡ | j  d¡}q|S ©Nr   )re   r   Ú_is_section_breakÚ_is_indentedÚappendr$   )r   r‚   r{   Úliner   r   r   Ú_consume_indented_blockþ   s    ÿþ
þz'GoogleDocstring._consume_indented_blockc                 C  s4   g }| j r0| j  d¡r0|  ¡ s0| | j  ¡ ¡ q|S rƒ   )re   r   Ú_is_section_headerr†   r$   ©r   r{   r   r   r   Ú_consume_contiguous	  s    
ÿþz#GoogleDocstring._consume_contiguousc                 C  s<   g }| j  d¡}| j r8|s8| | j  ¡ ¡ | j  d¡}q|S rƒ   )re   r   r†   r$   ©r   r{   r‡   r   r   r   Ú_consume_empty  s    
zGoogleDocstring._consume_emptyTFÚboolútuple[str, str, list[str]]©Ú
parse_typeÚprefer_typer   c                 C  sÎ   | j  ¡ }|  |¡\}}}|d|  }}}	|rTt |¡}
|
rT|
 d¡ ¡ }|
 d¡}|  |¡}|rp|sp|| }}|rŽ| jj	rŽt
|| jjpŠi ƒ}|  |¡d }|	g|  |  |¡¡ }|  || j¡ ¡ }|||fS )Nr1   r   é   )re   r$   Ú_partition_field_on_colonÚ_google_typed_arg_regexÚmatchÚgroupÚstripÚ_escape_args_and_kwargsrX   Únapoleon_preprocess_typesr/   Únapoleon_type_aliasesÚ_get_indentÚ_dedentrˆ   r#   r{   )r   r‘   r’   r‡   ÚbeforeÚcolonÚafterr^   r,   Ú_descr–   r‚   Ú_descsr   r   r   Ú_consume_field  s"    




zGoogleDocstring._consume_fieldú list[tuple[str, str, list[str]]])r‘   r’   Úmultipler   c           	      C  sv   |   ¡  g }|  ¡ sr|  ||¡\}}}|rT|rT| d¡D ]}| | ¡ ||f¡ q8q|s`|s`|r| |||f¡ q|S )Nú,)r   r„   r£   Úsplitr†   r˜   )	r   r‘   r’   r¥   Úfieldsr^   r,   r¡   r:   r   r   r   Ú_consume_fields3  s    zGoogleDocstring._consume_fieldsztuple[str, list[str]]c                 C  sb   | j  ¡ }|  |¡\}}}|r"|s4|| }}||7 }|g|  |  ¡ ¡ }|  || j¡ ¡ }||fS r   )re   r$   r”   r   Ú_consume_to_endr#   rX   r{   )r   r‡   r,   rŸ   r¡   r¢   r   r   r   Ú_consume_inline_attribute@  s    

z)GoogleDocstring._consume_inline_attribute©Úpreprocess_typesr   c           	      C  sª   |   |  ¡ ¡}|r¢|  |d ¡\}}}dd|  }}}|rb|rR|g|dd …  }n|dd … }|}|r„|r„| jjr„t|| jjp€i ƒ}|  || j¡ ¡ }|||fgS g S d S )Nr   r1   r   )	r   Ú_consume_to_next_sectionr”   rX   rš   r/   r›   r#   r{   )	r   r­   r{   rž   rŸ   r    r^   r,   r¡   r   r   r   Ú_consume_returns_sectionJ  s     ÿz(GoogleDocstring._consume_returns_sectionc                 C  s   |   |  ¡ ¡}|S r   )r   r®   rŠ   r   r   r   Ú_consume_usage_sectionb  s    z&GoogleDocstring._consume_usage_sectionc                 C  s*   | j  ¡ }| d¡}| ¡ | jkr&|}|S )Nú:)re   r$   r˜   ÚlowerrA   )r   ÚsectionZstripped_sectionr   r   r   Ú_consume_section_headerf  s
    

z'GoogleDocstring._consume_section_headerc                 C  s    g }| j r| | j  ¡ ¡ q|S r   )re   r†   r$   rŠ   r   r   r   rª   m  s    zGoogleDocstring._consume_to_endc                 C  s2   |   ¡  g }|  ¡ s&| | j ¡ ¡ q||   ¡  S r   )r   r„   r†   re   r$   rŠ   r   r   r   r®   s  s
    z(GoogleDocstring._consume_to_next_section)r{   Úfullr   c                   s2   |rdd„ |D ƒS |   |¡‰ ‡ fdd„|D ƒS d S )Nc                 S  s   g | ]}|  ¡ ‘qS r   )Úlstrip©Ú.0r‡   r   r   r   Ú
<listcomp>|  s     z+GoogleDocstring._dedent.<locals>.<listcomp>c                   s   g | ]}|ˆ d … ‘qS r   r   r·   ©Ú
min_indentr   r   r¹     s     )Ú_get_min_indent)r   r{   rµ   r   rº   r   r   z  s    
zGoogleDocstring._dedent©r:   r   c                 C  sp   |  d¡r(t| jddƒr(|d d… d }|d d… dkrHd|dd …  S |d d	… d
krhd|d	d …  S |S d S )Nr	   Zstrip_signature_backslashFéÿÿÿÿz\_r“   ú**z\*\*r   Ú*z\*)ÚendswithÚgetattrrX   ©r   r:   r   r   r   r™     s    z'GoogleDocstring._escape_args_and_kwargs)Údescr   c                 C  sx   |   |¡rdg| }n^|d  d¡rt|dd … }|  |d ¡}|  |¡}||kr\dg| }nd|d g|  |d¡ }|S )Nr1   r   ú::r   é   )Ú_is_listrÁ   rœ   Ú_get_initial_indentÚ_indent)r   rÄ   Z
desc_blockr‚   Zblock_indentr   r   r   Ú_fix_field_descŒ  s    

zGoogleDocstring._fix_field_desc)Ú
admonitionr{   r   c                 C  sn   |   |¡}t|ƒdkr2d|› d|d  ¡ › dgS |r^|  |  |¡d¡}d| dg| dg S d| dgS d S )Nr   z.. z:: r   r1   é   z.. %s::)Ú_strip_emptyr   r˜   rÉ   r   )r   rË   r{   r   r   r   Ú_format_admonition™  s    
z"GoogleDocstring._format_admonitionú
str | None)Úprefixr{   Úpaddingr   c                 C  sv   |rl|d krdt |ƒ }g }t|ƒD ]B\}}|dkrH| ||  ¡ ¡ q$|r\| || ¡ q$| d¡ q$|S |gS d S )Nú r   r1   )r   Ú	enumerater†   rd   )r   rÐ   r{   rÑ   Zresult_linesÚir‡   r   r   r   Ú_format_block£  s    zGoogleDocstring._format_blockÚparamÚtype)r¨   Ú
field_roleÚ	type_roler   c           	   	   C  s˜   g }|D ]„\}}}|   |¡}t|ƒrT|  |¡}d|› d|› d}| |  ||¡¡ n| d|› d|› d¡ |r| d|› d|› d|› ¡ q|dg S )Nr±   rÒ   ú: r1   )rÍ   ÚanyrÊ   ÚextendrÕ   r†   )	r   r¨   rØ   rÙ   r{   r^   r,   r¡   Úfieldr   r   r   Ú_format_docutils_paramsµ  s    

z'GoogleDocstring._format_docutils_params)r^   r,   r¡   r   c                 C  sæ   |   |¡}t|ƒ}|rdnd}|rp|r^d|krFd|› d|› d|› }qnd|› d|› d|› }q d|› d|› }n0|rœd|krŠ|› |› }q d	|› d	|› }nd}|rÜ|  |¡}|d
 rÐ||d
  g|dd …  S |g| S n|gS d S )Nz -- r1   ú`r¿   z** (ú)z** (*z*)rÀ   r   r   )rÍ   rÛ   rÊ   )r   r^   r,   r¡   Zhas_descÚ	separatorrÝ   r   r   r   Ú_format_fieldÆ  s(    

zGoogleDocstring._format_field)Ú
field_typer¨   r   c           
      C  s®   d|  ¡  }dt|ƒ }t|ƒdk}g }|D ]f\}}}|  |||¡}	|r||rd| |  |d |	¡¡ q’| |  |d |	¡¡ q,| |  |d |	¡¡ q,|rª|d rª| d¡ |S )Nz:%s:rÒ   r   z * r¾   r1   )r˜   r   râ   rÜ   rÕ   r†   )
r   rã   r¨   rÑ   Úmultir{   r^   r,   r¡   rÝ   r   r   r   Ú_format_fieldsã  s    
zGoogleDocstring._format_fieldsr   )Ú
peek_aheadr   c                 C  s@   | j  |¡}|| j jk	r<|r&|  |¡S |d7 }| j  |¡}qdS )Nr   r   )re   r   r   rœ   )r   ræ   r‡   r   r   r   Ú_get_current_indentö  s    
z#GoogleDocstring._get_current_indent)r‡   r   c                 C  s*   t |ƒD ]\}}| ¡ s|  S qt|ƒS r   )rÓ   Úisspacer   )r   r‡   rÔ   Úsr   r   r   rœ   ÿ  s    
zGoogleDocstring._get_indent)r{   r   c                 C  s    |D ]}|r|   |¡  S qdS rƒ   ©rœ   rŒ   r   r   r   rÈ     s    z#GoogleDocstring._get_initial_indentc                 C  s8   d }|D ]&}|r|   |¡}|d ks*||k r|}q|p6dS rƒ   rê   )r   r{   r»   r‡   r‚   r   r   r   r¼     s    
zGoogleDocstring._get_min_indentrÆ   )r{   r   r   c                   s   ‡ fdd„|D ƒS )Nc                   s   g | ]}d ˆ  | ‘qS )rÒ   r   r·   ©r   r   r   r¹     s     z+GoogleDocstring._indent.<locals>.<listcomp>r   )r   r{   r   r   rë   r   rÉ     s    zGoogleDocstring._indent)r‡   r‚   r   c                 C  s2   t |ƒD ]$\}}||kr dS | ¡ s dS qdS )NTF)rÓ   rè   )r   r‡   r‚   rÔ   ré   r   r   r   r…     s    zGoogleDocstring._is_indentedc                 C  sˆ   |sdS t  |d ¡rdS t |d ¡r,dS t|ƒdk sF|d  d¡rJdS |  |d ¡}|}|dd … D ]}|rh|  |¡} q€qh||kS )NFr   Tr“   rÅ   r   )Ú_bullet_list_regexr–   Ú_enumerated_list_regexr   rÁ   rœ   )r   r{   r‚   Znext_indentr‡   r   r   r   rÇ     s    
zGoogleDocstring._is_listc                 C  s|   | j  d¡ ¡ }t |¡}|rL| d¡| jkrL|  |¡}| jdd}||kS | j	rxt
 |¡rx| j	D ]}| |¡rb dS qbdS )Nr   r±   r   )ræ   TF)re   r   r²   Ú_google_section_regexr–   r˜   rA   rœ   rç   r@   Ú_directive_regexÚ
startswith)r   r³   r–   Zheader_indentZsection_indentÚdirective_sectionr   r   r   r‰   0  s    




z"GoogleDocstring._is_section_headerc                 C  s6   | j  d¡}| j  p4|  ¡ p4| jo4|o4|  || j¡ S rƒ   ©re   r   r‰   rg   r…   rh   )r   r‡   r   r   r   r„   >  s    ÿÿüz!GoogleDocstring._is_section_breakc                 C  s¤   | j jd k	r | j jD ]Š}t|tƒr4| j| j| ¡ < q|d dkrV| j| j|d  ¡ < q|d dkrx| j| j|d  ¡ < q| j 	|d  ¡ | j¡| j|d  ¡ < qd S )Nr   Zparams_styler   Zreturns_style)
rX   Znapoleon_custom_sectionsra   r+   Ú_parse_custom_generic_sectionrA   r²   Ú"_parse_custom_params_style_sectionÚ#_parse_custom_returns_style_sectionr   )r   Úentryr   r   r   ry   F  s    
ÿÿÿÿz%GoogleDocstring._load_custom_sectionsc                 C  sê   |   ¡ | _| jrP| jdkrPg }z|  ¡ }W n tk
r>   Y nX | j |¡ d S | jræ|  ¡ r¸zH|  ¡ }d| _	|  ¡ | _
t |¡r’|g|  ¡  }n| j| ¡  |ƒ}W 5 d| _	d| _
X n | jsÐ|  ¡ |   ¡  }n|  ¡ }| j |¡ qPd S )N)Ú	attributeÚdataÚpropertyFr   T)r   rf   r^   r]   Ú_parse_attribute_docstringr    rÜ   re   r‰   rg   rh   r´   rç   rï   r–   r®   rA   r²   r‹   )r   Úresr³   r{   r   r   r   rz   \  s0    



zGoogleDocstring._parse)rË   r³   r   c                 C  s   |   ¡ }|  ||¡S r   )r®   rÎ   )r   rË   r³   r{   r   r   r   rk   |  s    z!GoogleDocstring._parse_admonitionc                 C  s4   |   ¡ \}}|  dd|¡}|r0| dd| g¡ |S )Nr1   ú	:type: %s)r«   râ   rÜ   )r   r,   r¡   r{   r   r   r   rú     s
    z*GoogleDocstring._parse_attribute_docstring©r³   r   c                 C  sü   g }|   ¡ D ]Ø\}}}|s$|  |¡}| jjrbd| }| |  ||¡¡ |rä| d|› d|› ¡ q| d| ¡ | jrŠd| jkrŠ| d¡ | d¡ |  dd|¡}| |  	|d¡¡ |rÚ| d¡ | |  	d	| gd¡¡ | d¡ q| jjrø| d¡ |S )
Nz
:ivar %s: z	:vartype rÚ   z.. attribute:: Únoindexú   :noindex:r1   rÌ   rü   )
r©   Ú_lookup_annotationrX   Znapoleon_use_ivarrÜ   rÕ   r†   r`   râ   rÉ   )r   r³   r{   r^   r,   r¡   rÝ   r¨   r   r   r   rl   ˆ  s,    




z)GoogleDocstring._parse_attributes_sectionc                 C  s6   t dƒt dƒdœ}| jj}| | ¡ |¡}|  ||¡S )NZExampleZExamples)rO   rP   )r	   rX   Z$napoleon_use_admonition_for_examplesr   r²   Ú_parse_generic_section)r   r³   ÚlabelsÚuse_admonitionÚlabelr   r   r   rm   ¢  s    þz'GoogleDocstring._parse_examples_sectionc                 C  s   |   |d¡S )NF)r  ©r   r³   r   r   r   ró   «  s    z-GoogleDocstring._parse_custom_generic_sectionc                 C  s   |   ||  ¡ ¡S r   )rå   r©   r  r   r   r   rô   ¯  s    z2GoogleDocstring._parse_custom_params_style_sectionc                 C  s   | j dd}|  ||¡S )NT©r­   )r¯   rå   ©r   r³   r¨   r   r   r   rõ   ²  s    z3GoogleDocstring._parse_custom_returns_style_sectionc                 C  s6   ddg}ddg}|   ¡ }|  |d¡}|| | dg S )Nz.. rubric:: Usage:r1   z.. code-block:: pythonrÌ   )r°   rÉ   )r   r³   ÚheaderÚblockr{   r   r   r   Ú_parse_usage_section¶  s
    z$GoogleDocstring._parse_usage_section)r³   r  r   c                 C  s\   |   |  ¡ ¡}|  |¡}|r2d| }|  |d¡}nd| }|rP|dg| dg S |dgS d S )Nz.. admonition:: %srÌ   z.. rubric:: %sr1   )rÍ   r®   r   rÉ   )r   r³   r  r{   r  r   r   r   r  ½  s    
z&GoogleDocstring._parse_generic_sectionc                 C  s4   |   ¡ }| jjr | j|dddS |  tdƒ|¡S d S )NÚkeywordZkwtype)rØ   rÙ   zKeyword Arguments)r©   rX   Znapoleon_use_keywordrÞ   rå   r	   r  r   r   r   rn   Ê  s    ýz0GoogleDocstring._parse_keyword_arguments_sectionc                 C  sn   g }| j ddD ]X\}}}| d| ¡ | jrBd| jkrB| d¡ |r^| dg|  |d¡ ¡ | d¡ q|S )NF)r‘   z.. method:: %srþ   rÿ   r1   rÌ   )r©   r†   r`   rÜ   rÉ   )r   r³   r{   r^   r,   r¡   r   r   r   ro   Ô  s    
z&GoogleDocstring._parse_methods_sectionc                 C  s   | j j}|  tdƒ|¡S )NZNotes)rX   Z!napoleon_use_admonition_for_notesr  r	   ©r   r³   r  r   r   r   rp   ß  s    z$GoogleDocstring._parse_notes_sectionc                 C  s:   | j jr| jdd}|  |¡S |  ¡ }|  tdƒ|¡S d S )NT©r¥   zOther Parameters©rX   Znapoleon_use_paramr©   rÞ   rå   r	   r  r   r   r   rq   ã  s
    
z/GoogleDocstring._parse_other_parameters_sectionc                 C  s:   | j jr| jdd}|  |¡S |  ¡ }|  tdƒ|¡S d S )NTr  Z
Parametersr  r  r   r   r   rj   ì  s
    
z)GoogleDocstring._parse_parameters_sectionc           
      C  sÈ   | j ddd}g }|D ]ž\}}}| j |¡}|rF| d¡rF| d¡}n$t |¡rj| d¡}||d d… }|rvd| nd	}|  |¡}t|ƒršdd
 |¡ nd	}	| 	d|› d|	› ¡ q|rÄ| 	d	¡ |S )NFT)r‘   r’   r:   rß   r   r¾   rÒ   r1   z
    z:raisesr±   )
r©   Ú	_name_rgxr–   r—   Ú_xref_regexÚfindrÍ   rÛ   r~   r†   )
r   r³   r¨   r{   r^   r,   r¡   ÚmÚposr¢   r   r   r   rt   õ  s     



z%GoogleDocstring._parse_raises_sectionc                 C  s:   | j jr| jdd}|  |¡S |  ¡ }|  tdƒ|¡S d S )NTr  ZReceivesr  r  r   r   r   rr     s
    
z'GoogleDocstring._parse_receives_sectionc                 C  s   | j j}|  tdƒ|¡S )NZ
References)rX   Z&napoleon_use_admonition_for_referencesr  r	   r  r   r   r   ru     s    z)GoogleDocstring._parse_references_sectionc           
      C  sØ   |   ¡ }t|ƒdk}|rdn| jj}g }|D ]\}}}|rJ|  |d|¡}	n|  |||¡}	|rˆ|rt| |  d|	¡¡ q¼| |  d|	¡¡ q,t|	ƒr¢| |  d|	¡¡ |r,|r,| d| dg¡ q,|rÔ|d rÔ| d¡ |S )	Nr   Fr1   z          * z:returns: * z
:returns: z
:rtype: %sr¾   )	r¯   r   rX   Znapoleon_use_rtyperâ   rÜ   rÕ   rÛ   r†   )
r   r³   r¨   rä   Z	use_rtyper{   r^   r,   r¡   rÝ   r   r   r   rs     s&    
z&GoogleDocstring._parse_returns_sectionc                 C  s   |   d|¡S ©NÚseealso)rk   r  r   r   r   rv   .  s    z'GoogleDocstring._parse_see_also_sectionc                 C  s   |   tdƒ|  ¡ ¡S )NZWarns)rå   r	   r©   r  r   r   r   rw   1  s    z$GoogleDocstring._parse_warns_sectionc                 C  s   | j dd}|  tdƒ|¡S )NTr  ZYields)r¯   rå   r	   r  r   r   r   rx   4  s    z%GoogleDocstring._parse_yields_sectionztuple[str, str, str]c           	      C  sÀ   g }g }d}d}t t |¡ƒD ]‚\}}|r6| |¡ qt |¡}|d dkr–|r–d}|| ¡ | ¡ … }| |d | ¡ … ¡ | || ¡ d … ¡ q| |¡ qd |¡ 	¡ |d |¡ 	¡ fS )Nr1   Fr“   r   T)
rÓ   Ú_xref_or_code_regexr§   r†   Ú_single_colon_regexÚsearchÚstartÚendr~   r˜   )	r   r‡   Zbefore_colonZafter_colonrŸ   Zfound_colonrÔ   Úsourcer  r   r   r   r”   8  s$    
þz)GoogleDocstring._partition_field_on_colonc                 C  sŒ   |rˆd}t |ƒD ]\}}|r|} q&q|dkr2g }d}ttt|ƒƒƒD ]}|| }|rF|} q`qF|dksx|d t|ƒk rˆ|||d … }|S )Nr¾   r   r   )rÓ   ÚreversedÚranger   )r   r{   r  rÔ   r‡   r  r   r   r   rÍ   N  s"    zGoogleDocstring._strip_empty)r^   r   c                 C  sv   | j jrr| jdkrr| jrrt| dƒsXt| j di ƒ}| t| j di ƒpDi ¡ t| jd |ƒ| _|| jkrrt	| j| dƒS dS )N)r>   r=   Ú	exceptionÚ_annotationsZautodoc_type_aliasesr›   zfully-qualified-except-typingr1   )
rX   Znapoleon_attr_annotationsr]   r_   ri   rÂ   Úupdater   r  r   )r   r^   Úlocalnsr   r   r   r   a  s"    
  ÿþ

ÿz"GoogleDocstring._lookup_annotation)NNr1   r1   NN)r   )TF)TFF)F)F)N)rÖ   r×   )r   )rÆ   )r   )Ar%   r&   r'   r(   ÚreÚcompileÚXr  r|   r   r{   rˆ   r‹   r   r£   r©   r«   r¯   r°   r´   rª   r®   r   r™   rÊ   rÎ   rÕ   rÞ   râ   rå   rç   rœ   rÈ   r¼   rÉ   r…   rÇ   r‰   r„   ry   rz   rk   rú   rl   rm   ró   rô   rõ   r
  r  rn   ro   rp   rq   rj   rt   rr   ru   rs   rv   rw   rx   r”   rÍ   r   r   r   r   r   r0   S   s   >ÿ      øS  ÿ
 ÿ   ÿ		 	
			r0   r€   )Útokensr   c                   s2   t  | ¡}d‰ ‡ fdd„‰‡fdd„}t||ƒƒS )N©ÚoptionalÚdefaultc                 3  s¶   d}d }z|   ¡ }W n tk
r,   Y q²Y nX |dkr<|}q| ¡ sFq|ˆ krl|  |¡ |d k	r²|  |¡ q²|d k	r~|V  d }|dkr|d7 }n|dkr |d8 }|V  |dkrq²qd S )Nr   ú, Ú{r   Ú})r   Ú
IndexErrorr˜   Ú
appendleft)r%  Zopen_bracesZprevious_tokenÚtoken)Úkeywordsr   r   Útakewhile_setv  s4    



z,_recombine_set_tokens.<locals>.takewhile_setc                 3  sV   z|   ¡ }W n tk
r$   Y qRY nX |dkrJ|  d¡ d ˆ | ƒ¡V  q |V  q d S )Nr*  r1   )r   r,  r-  r~   )r%  r.  )r0  r   r   Úcombine_setš  s    

z*_recombine_set_tokens.<locals>.combine_set)ÚcollectionsÚdequeÚlist)r%  Ztoken_queuer1  r   )r/  r0  r   Ú_recombine_set_tokensr  s
    
$r5  )Úspecr   c                   s$   dd„ ‰ ‡ fdd„t  | ¡D ƒ}|S )Nc                 S  s6   t  | ¡r,| d d… }| dd … }|d|gS | gS d S )Né   é   rÒ   )Ú_default_regexr–   )Úitemr(  Úotherr   r   r   Úpostprocess«  s
    

z(_tokenize_type_spec.<locals>.postprocessc                   s"   g | ]}ˆ |ƒD ]}|r|‘qqS r   r   )r¸   Z	raw_tokenr:  ©r<  r   r   r¹   ¶  s
   
 ýz'_tokenize_type_spec.<locals>.<listcomp>)Ú_token_regexr§   )r6  r%  r   r=  r   Ú_tokenize_type_specª  s
    
þr?  rÏ   )r.  Úlocationr   c                 C  s(  dd„ }|   d¡s|  d¡r$d}n || ƒsh|   d¡r@|  d¡sh|   d¡rT|  d¡sh|   d¡rn|  d¡rnd	}n¶|   d¡r’tjtd
ƒ| |d d	}n’|  d¡r¶tjtdƒ| |d d	}nn|   d¡rÚtjtdƒ| |d d	}nJ|  d¡rþtjtdƒ| |d d	}n&| dkrd}nt | ¡r d}nd}|S )Nc                 S  s,   zt | ƒ W n tk
r"   Y dS X dS d S )NFT)ÚcomplexÚ
ValueError)r.  r   r   r   Ú
is_numericÀ  s
    z_token_type.<locals>.is_numericrÒ   Ú	delimiterr*  r+  ú"ú'Úliteralz-invalid value set (missing closing brace): %s©r@  z-invalid value set (missing opening brace): %s)rF  rE  z4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %sr&  ÚcontrolÚ	referencer;   )rð   rÁ   ÚloggerrK   r
   r  r–   )r.  r@  rC  Útype_r   r   r   Ú_token_type¿  sh    	ÿþþýýüü
ý
ý
ý
ý
rM  Údict)r,   r@  r-   r   c                   sp   dd„ ‰ t | ƒ}t|ƒ}‡fdd„|D ƒ}dd„ ‡ ‡fdd„dd„ d	d„ d
d„ dœ‰d ‡fdd„|D ƒ¡}|S )Nc                 S  sP   |  | | ¡}|tkr"|dkr"d}n|dkr6|dkr6d}t |¡d krL|| }|S )Nr.   ú	:obj:`%s`z...z:obj:`%s <Ellipsis>`)r   Ú_SINGLETONSr  r–   )r;   r-   Zdefault_translationÚtranslationr   r   r   Úconvert_objý  s    z-_convert_numpy_type_spec.<locals>.convert_objc                   s   g | ]}|t |ˆ ƒf‘qS r   )rM  )r¸   r.  rH  r   r   r¹     s   ÿz,_convert_numpy_type_spec.<locals>.<listcomp>c                 S  s   d|  S )Nz``%s``r   ©Úxr   r   r   Ú<lambda>  ó    z*_convert_numpy_type_spec.<locals>.<lambda>c                   s   ˆ | ˆdƒS )Nr.   r   rS  )rR  r-   r   r   rU    rV  c                 S  s   d|  S )Nz*%s*r   rS  r   r   r   rU    rV  c                 S  s   | S r   r   rS  r   r   r   rU    rV  c                 S  s   | S r   r   rS  r   r   r   rU    rV  )rG  r;   rI  rD  rJ  r1   c                 3  s    | ]\}}ˆ   |¡|ƒV  qd S r   )r   )r¸   r.  rL  )Ú
convertersr   r   Ú	<genexpr>  s     z+_convert_numpy_type_spec.<locals>.<genexpr>)r?  r5  r~   )r,   r@  r-   r%  Zcombined_tokensÚtypesZ	convertedr   )rR  rW  r@  r-   r   Ú_convert_numpy_type_specú  s    
þûrZ  c                
      sÈ   e Zd ZdZd,dddddddd	d
œ‡ fdd„Zddœdd„Zdddœ‡ fdd„Zd-ddddœdd„Zd.dddœdd„Zddœdd „Z	ddœd!d"„Z
ddœd#d$„Zdd%d&œd'd(„Zd%d%d)œd*d+„Z‡  ZS )/Ú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.
    <BLANKLINE>
    Extended description.
    <BLANKLINE>
    :param arg1: Description of `arg1`
    :type arg1: int
    :param arg2: Description of `arg2`
    :type arg2: str
    <BLANKLINE>
    :returns: Description of return value.
    :rtype: str
    <BLANKLINE>

    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.

    Nr1   r2   r3   r4   r+   r   r   r5   c              	     s$   dg| _ tƒ  |||||||¡ d S )Nz
.. index::)r@   r   r|   )r   r6   r7   r8   r9   r:   r;   r<   r"   r   r   r|   }  s    
zNumpyDocstring.__init__rÏ   r   c                 C  sp   z| j d k	rt | j ¡nd }W n tk
r6   d }Y nX | j}|d krR|d krRd S |d kr^d}d |d| g¡S )Nr1   r±   zdocstring of %s)r_   rY   ÚgetfileÚ	TypeErrorr^   r~   )r   Úfilepathr:   r   r   r   Ú_get_locationŠ  s    
zNumpyDocstring._get_locationr½   c                   s:   t ƒ j‰ d|kr.d ‡ fdd„| d¡D ƒ¡S ˆ |ƒS d S )Nr)  c                 3  s   | ]}ˆ |ƒV  qd S r   r   )r¸   rÖ   ©Úfuncr   r   rX  œ  s     z9NumpyDocstring._escape_args_and_kwargs.<locals>.<genexpr>)r   r™   r~   r§   rÃ   r"   r`  r   r™   ˜  s    z&NumpyDocstring._escape_args_and_kwargsTFrŽ   r   r   c           	      C  sÆ   | j  ¡ }|r |  |¡\}}}n
|d }}| ¡ | ¡  }}|  |¡}|rX|sX|  |¡}|rj|sj|| }}| jjrŒt||  	¡ | jj
p†i d}|  |¡d }|  |  |¡¡}|  || j¡ ¡ }|||fS )Nr1   )r@  r-   r   )re   r$   r”   r˜   r™   r   rX   rš   rZ  r_  r›   rœ   r   rˆ   r#   r{   )	r   r‘   r’   r‡   r^   r	   r,   r‚   r¡   r   r   r   r£      s(    





ýzNumpyDocstring._consume_fieldr¤   r¬   c                 C  s   | j ddS )NT)r’   )r©   )r   r­   r   r   r   r¯   ¼  s    z'NumpyDocstring._consume_returns_sectionc                 C  s"   | j  ¡ }t |¡s| j  ¡  |S r   )re   r$   rï   r–   r  r   r   r   r´   À  s    


z&NumpyDocstring._consume_section_headerc                 C  sT   | j  d¡| j  d¡ }}| j  pR|  ¡ pRddg||gkpR| joR|oR|  || j¡ S )Nr   r   r1   rò   )r   Úline1Úline2r   r   r   r„   Ç  s    ÿþÿûz NumpyDocstring._is_section_breakc                 C  st   | j  d¡| j  d¡ }}| ¡ }|| jkrDt|tƒrDtt |¡ƒS | j	rpt
 |¡rp| j	D ]}| |¡rZ dS qZdS )Nr   r   TF)re   r   r²   rA   ra   r+   rŽ   Ú_numpy_section_regexr–   r@   rï   rð   )r   r³   Ú	underlinerñ   r   r   r   r‰   Ð  s    


z!NumpyDocstring._is_section_headerr€   rý   c                 C  s:   |   ¡ }z|  |¡W S  tk
r4   |  d|¡ Y S X d S r  )r®   Ú _parse_numpydoc_see_also_sectionrB  rÎ   )r   r³   r{   r   r   r   rv   Ü  s
    z&NumpyDocstring._parse_see_also_section)Úcontentr   c                   s  g ‰ dddœ‡fdd„‰ddddœ‡ ‡fd	d
„}‡fdd„‰d}g }|D ]ú}|  ¡ sVqHˆj |¡}|rÐ|| ¡ d…   ¡  d¡rÐ|||ƒ |d| ¡ … || ¡ d…  }}| dd¡d   ¡ g}|d sÎg }qH| d¡s,|||ƒ d}d|kr| d¡D ]}|  ¡  rþ||g ƒ  qþn|  ¡ rB|}qH|dk	rH| |  ¡ ¡ qH|||ƒ ˆ sXg S ‡fdd„ˆ D ƒ‰ g }d}	ˆ D ]Š\}
}}|ršd|› d|
› d}nd|
 }|s®|	rÄ|dg7 }||g7 }n|d  d| 7  < |rú|ˆ d |¡g¡7 }d}	nd}	qv|dg7 }ˆ 	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

        r+   ztuple[str, str | None])Útextr   c                   sP   ˆ j  | ¡}|r@| ¡ }|d dkr0|d dfS |d |d fS td|  ƒ‚dS )zMatch ':role:`name`' or 'name'r   NrÌ   r“   z%s is not a item name)r  r–   ÚgroupsrB  )rh  r  Úgr!   r   r   Úparse_item_nameñ  s    zHNumpyDocstring._parse_numpydoc_see_also_section.<locals>.parse_item_namer€   r   )r:   Úrestr   c                   s6   | sd S ˆ| ƒ\} }ˆ   | t|ƒ|f¡ |d d …= d S r   )r†   r4  )r:   rl  Úrole)Úitemsrk  r   r   Ú	push_itemü  s
    zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.push_itemc                   sn   ˆ j j}|d k	s|s| ||fS | | | ¡}ˆ j |¡}|sD|||fS | ¡ }|d }|d pb|d }|||fS )Nrm  r:   Zname2)rX   r›   r   r  r–   Ú	groupdict)ra  Údescriptionrm  r-   Z
translatedr–   ri  Únew_funcr!   r   r   Ú	translate  s    

zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.translateNr±   r   r   rÒ   r¦   c                   s   g | ]\}}}ˆ |||ƒ‘qS r   r   )r¸   ra  rq  rm  )rs  r   r   r¹   2  s   ÿzCNumpyDocstring._parse_numpydoc_see_also_section.<locals>.<listcomp>Tz:`rß   rO  r1   r¾   z, %sFr  )
r˜   r  r–   r  rð   r§   r†   rÉ   r~   rÎ   )r   rg  ro  Zcurrent_funcrl  r‡   r  ra  r{   Zlast_had_descr:   rÄ   rm  Úlinkr   )rn  rk  r   rs  r   rf  ã  sb    
"





þ

z/NumpyDocstring._parse_numpydoc_see_also_section)NNr1   r1   NN)TF)F)r%   r&   r'   r(   r|   r_  r™   r£   r¯   r´   r„   r‰   rv   rf  r*   r   r   r"   r   r[     s"   _      ø"	r[  )N)1r(   Ú
__future__r   r2  rY   r"  Ú	functoolsr   Útypingr   r   Zsphinx.applicationr   Zsphinx.configr   ZSphinxConfigZsphinx.localer	   r
   Zsphinx.utilr   Zsphinx.util.typingr   r   Ú	getLoggerr%   rK  r#  rï   rî   r•   rd  r  r  r  rì   rí   r>  r9  rP  r3  r   r/   r0   r5  r?  rM  rZ  r[  r   r   r   r   Ú<module>   sd   





ÿÿ
ÿÿÿ      %8< ÿ&