B
    öÀ„\‚  ã               @   sÜ   d 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 ddlm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G dd„ deƒZG dd„ deƒZdS )zì
    sphinx.ext.napoleon.docstring
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


    Classes for docstring parsing and formatting.


    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
é    N)Úpartial)Ústring_typesÚu)Úrange)Úmodify_iter)Ú_)ÚUnicodeMixinz
\.\. \S+::z^(\s|\w)+:\s*$z\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z(?<!:):(?!:)z.(:(?:[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*$)c               @   sÌ  e Zd ZdZdudd„Zdd„ Zdd	„ Zdvdd„Zdd„ Zdd„ Z	dwdd„Z
dxdd„Zdd„ Zdd„ Zdd„ Zdd„ Zdd „ Zd!d"„ Zdyd#d$„Zd%d&„ Zd'd(„ Zd)d*„ Zdzd+d,„Zd{d/d0„Zd1d2„ Zd3d4„ Zd|d6d7„Zd8d9„ Zd:d;„ Zd<d=„ Zd}d?d@„Zd~dAdB„ZdCdD„ Z dEdF„ Z!dGdH„ Z"dIdJ„ Z#dKdL„ Z$dMdN„ Z%dOdP„ Z&dQdR„ Z'dSdT„ Z(dUdV„ Z)dWdX„ Z*dYdZ„ Z+d[d\„ Z,d]d^„ Z-d_d`„ Z.dadb„ Z/dcdd„ Z0dedf„ Z1dgdh„ Z2didj„ Z3dkdl„ Z4dmdn„ Z5dodp„ Z6dqdr„ Z7dsdt„ Z8d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>

    NÚ c       	      C   s´  || _ || _| j s4ddlm} | jr,| jjp0|ƒ | _ |snt |¡rHd}n&t |¡rXd}nt|t	j
ƒrjd}nd}|| _|| _|| _|| _t|tƒr˜| ¡ }|| _t|dd„ d	| _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%t| jdƒt| jdƒt| jdƒt| jdƒ| j&| j'| j'dœ| _(|  )¡  |  *¡  d S )Nr   )ÚConfigÚclassÚmoduleÚfunctionÚobjectc             S   s   |   ¡ S )N)Úrstrip)Ús© r   ú<lib/python3.7/site-packages/sphinx/ext/napoleon/docstring.pyÚ<lambda>‡   s    z*GoogleDocstring.__init__.<locals>.<lambda>)ZmodifierFÚ_directive_sectionsÚ	_sectionsÚ	attentionÚcautionÚdangerÚerrorÚhintÚ	importantÚnoteÚtipÚtodoÚwarning)ÚargsZ	argumentsr   Z
attributesr   r   r   ÚexampleÚexamplesr   r   zkeyword argszkeyword argumentsÚmethodsr   Znoteszother parametersZ
parametersÚreturnZreturnsZraisesZ
referenceszsee alsor   r   r    ÚwarningsZwarnsÚyieldZyields)+Ú_configZ_appZsphinx.ext.napoleonr   ÚconfigÚinspectZisclassZismoduleÚ
isinstanceÚcollectionsÚCallableÚ_whatÚ_nameZ_objZ_optr   Ú
splitlinesZ_linesr   Ú
_line_iterÚ_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_returns_sectionÚ_parse_raises_sectionÚ_parse_references_sectionÚ_parse_see_also_sectionÚ_parse_warns_sectionÚ_parse_yields_sectionr   Ú_load_custom_sectionsÚ_parse)	ÚselfÚ	docstringr)   ÚappÚwhatÚnameÚobjÚoptionsr   r   r   r   Ú__init__l   sv    














zGoogleDocstring.__init__c             C   s   t dƒ |  ¡ ¡S )z Return the parsed docstring in reStructuredText format.

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

        Ú
)r   ÚjoinÚlines)rF   r   r   r   Ú__unicode__³   s    
zGoogleDocstring.__unicode__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.

        )r2   )rF   r   r   r   rP   ¿   s    
zGoogleDocstring.linesé   c             C   sJ   g }| j  ¡ }x6|  ¡ sD|r(|  ||¡rD| t| j ƒ¡ | j  ¡ }qW |S )N)r1   ÚpeekÚ_is_section_breakÚ_is_indentedÚappendÚnext)rF   ÚindentrP   Úliner   r   r   Ú_consume_indented_blockË   s    

z'GoogleDocstring._consume_indented_blockc             C   s:   g }x0| j  ¡ r4| j  ¡ r4|  ¡ s4| t| j ƒ¡ qW |S )N)r1   Úhas_nextrS   Ú_is_section_headerrV   rW   )rF   rP   r   r   r   Ú_consume_contiguousÕ   s    
z#GoogleDocstring._consume_contiguousc             C   s@   g }| j  ¡ }x,| j  ¡ r:|s:| t| j ƒ¡ | j  ¡ }qW |S )N)r1   rS   r[   rV   rW   )rF   rP   rY   r   r   r   Ú_consume_emptyÞ   s    
zGoogleDocstring._consume_emptyTFc             C   s¬   t | jƒ}|  |¡\}}}|d|  }}}	|rPt |¡}
|
rP|
 d¡}|
 d¡}|  |¡}|rl|sl|| }}|  |¡d }|	g|  |  	|¡¡ }|  
|| j¡ ¡ }|||fS )Nr
   rR   é   )rW   r1   Ú_partition_field_on_colonÚ_google_typed_arg_regexÚmatchÚgroupÚ_escape_args_and_kwargsÚ_get_indentÚ_dedentrZ   Ú	__class__r(   rP   )rF   Ú
parse_typeÚprefer_typerY   ÚbeforeÚcolonÚafterr/   Ú_typeÚ_descrb   rX   Ú_descsr   r   r   Ú_consume_fieldç   s    





zGoogleDocstring._consume_fieldc             C   sL   |   ¡  g }x:|  ¡ sF|  ||¡\}}}|s4|s4|r| |||f¡ qW |S )N)r^   rT   rp   rV   )rF   rh   ri   Úfieldsr/   rm   rn   r   r   r   Ú_consume_fieldsý   s    
zGoogleDocstring._consume_fieldsc             C   sV   t | jƒ}|  |¡\}}}|s(|| }}|g|  |  ¡ ¡ }|  || j¡ ¡ }||fS )N)rW   r1   r`   rf   Ú_consume_to_endrg   r(   rP   )rF   rY   rm   rk   rn   ro   r   r   r   Ú_consume_inline_attribute  s    

z)GoogleDocstring._consume_inline_attributec             C   sˆ   |   |  ¡ ¡}|r€|  |d ¡\}}}dd|  }}}|rb|rR|g|dd …  }n|dd … }|}|  || j¡ ¡ }|||fgS g S d S )Nr   r
   rR   )rf   Ú_consume_to_next_sectionr`   rg   r(   rP   )rF   rP   rj   rk   rl   r/   rm   rn   r   r   r   Ú_consume_returns_section  s    z(GoogleDocstring._consume_returns_sectionc             C   s   |   |  ¡ ¡}|S )N)rf   ru   )rF   rP   r   r   r   Ú_consume_usage_section%  s    z&GoogleDocstring._consume_usage_sectionc             C   s*   t | jƒ}| d¡}| ¡ | jkr&|}|S )Nú:)rW   r1   ÚstripÚlowerr   )rF   ÚsectionZstripped_sectionr   r   r   Ú_consume_section_header*  s
    

z'GoogleDocstring._consume_section_headerc             C   s(   g }x| j  ¡ r"| t| j ƒ¡ qW |S )N)r1   r[   rV   rW   )rF   rP   r   r   r   rs   2  s    zGoogleDocstring._consume_to_endc             C   s6   |   ¡  g }x|  ¡ s(| t| jƒ¡ qW ||   ¡  S )N)r^   rT   rV   rW   r1   )rF   rP   r   r   r   ru   9  s
    
z(GoogleDocstring._consume_to_next_sectionc                s2   |rdd„ |D ƒS |   |¡‰ ‡ fdd„|D ƒS d S )Nc             S   s   g | ]}|  ¡ ‘qS r   )Úlstrip)Ú.0rY   r   r   r   ú
<listcomp>D  s    z+GoogleDocstring._dedent.<locals>.<listcomp>c                s   g | ]}|ˆ d … ‘qS )Nr   )r~   rY   )Ú
min_indentr   r   r   G  s    )Ú_get_min_indent)rF   rP   Zfullr   )r€   r   rf   A  s    
zGoogleDocstring._dedentc             C   sH   |d d… dkr d|dd …  S |d d… dkr@d|dd …  S |S d S )Nr_   z**z\*\*rR   Ú*z\*r   )rF   rJ   r   r   r   rd   I  s
    z'GoogleDocstring._escape_args_and_kwargsc             C   sx   |   |¡rdg| }n^|d  d¡rt|dd … }|  |d ¡}|  |¡}||kr\dg| }nd|d g|  |d¡ }|S )Nr
   r   z::rR   é   )Ú_is_listÚendswithre   Ú_get_initial_indentÚ_indent)rF   ÚdescZ
desc_blockrX   Zblock_indentr   r   r   Ú_fix_field_descR  s    

zGoogleDocstring._fix_field_descc             C   sj   |   |¡}t|ƒdkr.d||d  ¡ f dgS |rZ|  |  |¡d¡}d| dg| dg S d| dgS d S )NrR   z
.. %s:: %sr   r
   é   z.. %s::)Ú_strip_emptyÚlenry   r‡   rf   )rF   Ú
admonitionrP   r   r   r   Ú_format_admonition`  s    
z"GoogleDocstring._format_admonitionc             C   sz   |rp|d krdt |ƒ }g }xNt|ƒD ]B\}}|dkrJ| ||  ¡ ¡ q&|r^| || ¡ q&| d¡ q&W |S |gS d S )Nú r   r
   )rŒ   Ú	enumeraterV   r   )rF   ÚprefixrP   ÚpaddingZresult_linesÚirY   r   r   r   Ú_format_blockk  s    zGoogleDocstring._format_blockÚparamÚtypec       	      C   sˆ   g }xx|D ]p\}}}|   |¡}t|ƒrP|  |¡}d||f }| |  ||¡¡ n| d||f ¡ |r
| d|||f ¡ q
W |dg S )Nz:%s %s: z:%s %s:z
:%s %s: %sr
   )r‹   Úanyr‰   Úextendr”   rV   )	rF   rq   Ú
field_roleÚ	type_rolerP   r/   rm   rn   Úfieldr   r   r   Ú_format_docutils_params|  s    

z'GoogleDocstring._format_docutils_paramsc             C   sÎ   |   |¡}t|ƒ}|rdpd}|r\|rNd|kr>d|||f }qZd|||f }qˆd||f }n,|r„d|krvd||f }qˆd||f }nd}|rÄ|  |¡}|d	 r¸||d	  g|d
d …  S |g| S n|gS d S )Nz -- r
   ú`z**%s** (%s)%sz**%s** (*%s*)%sz**%s**%sz%s%sz*%s*%sr   rR   )r‹   r—   r‰   )rF   r/   rm   rn   Úhas_descÚ	separatorr›   r   r   r   Ú_format_field  s(    

zGoogleDocstring._format_fieldc       
      C   s²   d|  ¡  }dt|ƒ }t|ƒdk}g }xn|D ]f\}}}|  |||¡}	|r~|rf| |  |d |	¡¡ q”| |  |d |	¡¡ q.| |  |d |	¡¡ q.W |r®|d r®| d¡ |S )Nz:%s:r   rR   z * éÿÿÿÿr
   )ry   rŒ   r    r˜   r”   rV   )
rF   Ú
field_typerq   r’   ÚmultirP   r/   rm   rn   r›   r   r   r   Ú_format_fields«  s    
zGoogleDocstring._format_fieldsr   c             C   sT   | j  |d ¡| }x:|| j jkrN|r0|  |¡S |d7 }| j  |d ¡| }qW dS )NrR   r   )r1   rS   Úsentinelre   )rF   Ú
peek_aheadrY   r   r   r   Ú_get_current_indent¾  s    
z#GoogleDocstring._get_current_indentc             C   s*   x t |ƒD ]\}}| ¡ s
|S q
W t|ƒS )N)r   ÚisspacerŒ   )rF   rY   r“   r   r   r   r   re   È  s    zGoogleDocstring._get_indentc             C   s    x|D ]}|r|   |¡S qW dS )Nr   )re   )rF   rP   rY   r   r   r   r†   Ï  s    
z#GoogleDocstring._get_initial_indentc             C   sB   d }x4|D ],}|r
|   |¡}|d kr*|}q
||k r
|}q
W |p@dS )Nr   )re   )rF   rP   r€   rY   rX   r   r   r   r   Ö  s    

zGoogleDocstring._get_min_indentrƒ   c                s   ‡ fdd„|D ƒS )Nc                s   g | ]}d ˆ  | ‘qS )r   r   )r~   rY   )Únr   r   r   ä  s    z+GoogleDocstring._indent.<locals>.<listcomp>r   )rF   rP   r©   r   )r©   r   r‡   â  s    zGoogleDocstring._indentc             C   s2   x,t |ƒD ] \}}||krdS | ¡ s
dS q
W dS )NTF)r   r¨   )rF   rY   rX   r“   r   r   r   r   rU   æ  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 ¡}|}x$|dd … D ]}|rj|  |¡}P qjW ||kS )NFr   Tr_   z::rR   )Ú_bullet_list_regexrb   Ú_enumerated_list_regexrŒ   r…   re   )rF   rP   rX   Znext_indentrY   r   r   r   r„   ï  s    
zGoogleDocstring._is_listc             C   s|   | j  ¡  ¡ }t |¡}|rJ| d¡| jkrJ|  |¡}| jdd}||kS | j	rxt
 |¡rxx| j	D ]}| |¡rbdS qbW dS )Nrx   rR   )r¦   TF)r1   rS   rz   Ú_google_section_regexrb   ry   r   re   r§   r   Ú_directive_regexÚ
startswith)rF   r{   rb   Zheader_indentZsection_indentÚdirective_sectionr   r   r   r\     s    



z"GoogleDocstring._is_section_headerc             C   s8   | j  ¡ }| j  ¡  p6|  ¡ p6| jo6|o6|  || j¡ S )N)r1   rS   r[   r\   r3   rU   r4   )rF   rY   r   r   r   rT     s    
z!GoogleDocstring._is_section_breakc             C   sd   | j jd k	r`xR| j jD ]F}t|tƒr6| j| j| ¡ < q| j |d  ¡ | j¡| j|d  ¡ < qW d S )NrR   r   )r(   Znapoleon_custom_sectionsr+   r   Ú_parse_custom_generic_sectionr   rz   Úget)rF   Úentryr   r   r   rD     s    
z%GoogleDocstring._load_custom_sectionsc             C   sü   |   ¡ | _| jrZ| jdks$| jdkrZg }y|  ¡ }W n tk
rH   Y nX | j |¡ d S xœ| j ¡ rö|  	¡ rÈzH|  
¡ }d| _|  ¡ | _t |¡r¢|g|  ¡  }n| j| ¡  |ƒ}W d d| _d| _X n | jsà|  ¡ |   ¡  }n|  ¡ }| j |¡ q\W d S )NÚ	attributeÚdataTFr   )r^   r2   r/   r.   Ú_parse_attribute_docstringÚStopIterationr˜   r1   r[   r\   r|   r3   r§   r4   r­   rb   ru   r   rz   r]   )rF   Zresr{   rP   r   r   r   rE   *  s0    



zGoogleDocstring._parsec             C   s   |   ¡ }|  ||¡S )N)ru   rŽ   )rF   r   r{   rP   r   r   r   r7   M  s    z!GoogleDocstring._parse_admonitionc             C   s4   |   ¡ \}}|  dd|¡}|r0| dd| g¡ |S )Nr
   z	:type: %s)rt   r    r˜   )rF   rm   rn   rP   r   r   r   rµ   R  s
    z*GoogleDocstring._parse_attribute_docstringc             C   sÎ   g }x²|   ¡ D ]¦\}}}| jjrRd| }| |  ||¡¡ |r´| d||f ¡ q| d| dg¡ |  dd|¡}| |  |d¡¡ |rª| d¡ | |  d| gd¡¡ | d¡ qW | jjrÊ| d¡ |S )Nz
:ivar %s: z:vartype %s: %sz.. attribute:: r
   rŠ   z	:type: %s)rr   r(   Znapoleon_use_ivarr˜   r”   rV   r    r‡   )rF   r{   rP   r/   rm   rn   r›   rq   r   r   r   r8   Z  s"    

z)GoogleDocstring._parse_attributes_sectionc             C   s6   t dƒt dƒdœ}| jj}| | ¡ |¡}|  ||¡S )NZExampleZExamples)r"   r#   )r   r(   Z$napoleon_use_admonition_for_examplesr±   rz   Ú_parse_generic_section)rF   r{   ÚlabelsÚuse_admonitionZlabelr   r   r   r9   o  s
    z'GoogleDocstring._parse_examples_sectionc             C   s   |   |d¡S )NF)r·   )rF   r{   r   r   r   r°   y  s    z-GoogleDocstring._parse_custom_generic_sectionc             C   s6   ddg}ddg}|   ¡ }|  |d¡}|| | dg S )Nz.. rubric:: Usage:r
   z.. code-block:: pythonrŠ   )rw   r‡   )rF   r{   ÚheaderÚblockrP   r   r   r   Ú_parse_usage_section}  s
    z$GoogleDocstring._parse_usage_sectionc             C   s\   |   |  ¡ ¡}|  |¡}|r2d| }|  |d¡}nd| }|rP|dg| dg S |dgS d S )Nz.. admonition:: %srŠ   z.. rubric:: %sr
   )r‹   ru   rf   r‡   )rF   r{   r¹   rP   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)rr   r(   Znapoleon_use_keywordrœ   r¤   r   )rF   r{   rq   r   r   r   r:   “  s    z0GoogleDocstring._parse_keyword_arguments_sectionc             C   sX   g }xN| j ddD ]>\}}}| d| ¡ |rF| dg|  |d¡ ¡ | d¡ qW |S )NF)rh   z.. method:: %sr
   rŠ   )rr   rV   r˜   r‡   )rF   r{   rP   r/   rm   rn   r   r   r   r;   ž  s    z&GoogleDocstring._parse_methods_sectionc             C   s   | j j}|  tdƒ|¡S )NZNotes)r(   Z!napoleon_use_admonition_for_notesr·   r   )rF   r{   r¹   r   r   r   r<   ¨  s    z$GoogleDocstring._parse_notes_sectionc             C   s   |   tdƒ|  ¡ ¡S )NzOther Parameters)r¤   r   rr   )rF   r{   r   r   r   r=   ­  s    z/GoogleDocstring._parse_other_parameters_sectionc             C   s.   |   ¡ }| jjr|  |¡S |  tdƒ|¡S d S )NZ
Parameters)rr   r(   Znapoleon_use_paramrœ   r¤   r   )rF   r{   rq   r   r   r   r6   ±  s    
z)GoogleDocstring._parse_parameters_sectionc             C   s^  | j ddd}d}dt|ƒ }t|ƒdk}g }x|D ]\}}}	|  |	¡}	t|	ƒ}
|
r\dp^d}|ræd	|kprd
|k}tdd„ |D ƒƒ}|sœ|sœd||f }n"|
r²|r²d||f }nd||f }|
rÞ||	d  g|	dd …  }qê|g}n|	}|r&|r| |  |d |¡¡ n| |  |d |¡¡ q6| |  |d |¡¡ q6W |rZ|d rZ| d¡ |S )NFT)rh   ri   z:raises:r   rR   z -- r
   r   rx   c             s   s   | ]}|d kV  qdS )z 	
 Nr   )r~   Úcr   r   r   ú	<genexpr>Æ  s    z8GoogleDocstring._parse_raises_section.<locals>.<genexpr>z:exc:`%s`%sz*%s*%sz%s%sr   z * r¡   )rr   rŒ   r‹   r—   r˜   r”   rV   )rF   r{   rq   r¢   r’   r£   rP   r/   rm   rn   rž   rŸ   Zhas_refsZ	has_spacer›   r   r   r   r?   ¹  s:    

z%GoogleDocstring._parse_raises_sectionc             C   s   | j j}|  tdƒ|¡S )NZ
References)r(   Z&napoleon_use_admonition_for_referencesr·   r   )rF   r{   r¹   r   r   r   r@   à  s    z)GoogleDocstring._parse_references_sectionc       
      C   sÖ   |   ¡ }t|ƒdk}|rd}n| jj}g }x|D ]ˆ\}}}|rN|  |d|¡}	n|  |||¡}	|rŒ|rx| |  d|	¡¡ q¸| |  d|	¡¡ q0| |  d|	¡¡ |r0|r0| d| dg¡ q0W |rÒ|d rÒ| d¡ |S )	NrR   Fr
   z          * z:returns: * z
:returns: z
:rtype: %sr¡   )rv   rŒ   r(   Znapoleon_use_rtyper    r˜   r”   rV   )
rF   r{   rq   r£   Z	use_rtyperP   r/   rm   rn   r›   r   r   r   r>   å  s(    
z&GoogleDocstring._parse_returns_sectionc             C   s   |   d|¡S )NÚseealso)r7   )rF   r{   r   r   r   rA     s    z'GoogleDocstring._parse_see_also_sectionc             C   s   |   tdƒ|  ¡ ¡S )NZWarns)r¤   r   rr   )rF   r{   r   r   r   rB     s    z$GoogleDocstring._parse_warns_sectionc             C   s   |   ¡ }|  tdƒ|¡S )NZYields)rv   r¤   r   )rF   r{   rq   r   r   r   rC   
  s    z%GoogleDocstring._parse_yields_sectionc       	      C   sÄ   g }g }d}d}x”t t |¡ƒD ]‚\}}|r8| |¡ q t |¡}|d dkr˜|r˜d}|| ¡ | ¡ … }| |d | ¡ … ¡ | || ¡ d … ¡ q | |¡ q W d |¡ 	¡ |d |¡ 	¡ fS )Nr
   Fr_   r   T)
r   Ú_xref_regexÚsplitrV   Ú_single_colon_regexÚsearchÚstartÚendrO   ry   )	rF   rY   Zbefore_colonZafter_colonrk   Zfound_colonr“   ÚsourceÚmr   r   r   r`     s"    
z)GoogleDocstring._partition_field_on_colonc             C   s   |rŒd}xt |ƒD ]\}}|r|}P qW |dkr4g }d}x*ttt|ƒƒƒD ]}|| }|rJ|}P qJW |dks||d t|ƒk rŒ|||d … }|S )Nr¡   r   rR   )r   Úreversedr   rŒ   )rF   rP   rÅ   r“   rY   rÆ   r   r   r   r‹   &  s"    zGoogleDocstring._strip_empty)NNr
   r
   NN)rR   )TF)TF)F)N)r•   r–   )r   )rƒ   )rR   )9Ú__name__Ú
__module__Ú__qualname__Ú__doc__rM   rQ   rP   rZ   r]   r^   rp   rr   rt   rv   rw   r|   rs   ru   rf   rd   r‰   rŽ   r”   rœ   r    r¤   r§   re   r†   r   r‡   rU   r„   r\   rT   rD   rE   r7   rµ   r8   r9   r°   r¼   r·   r:   r;   r<   r=   r6   r?   r@   r>   rA   rB   rC   r`   r‹   r   r   r   r   r	   .   sp   = 
F

		




	
 




		#

'r	   c                   sj   e Zd ZdZd‡ fdd„	Zddd	„Zd
d„ Zdd„ Zdd„ Zdd„ Z	e
 de
j¡Zdd„ Z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.

    Nr
   c          	      s(   dg| _ tt| ƒ |||||||¡ d S )Nz
.. index::)r   ÚsuperrÎ   rM   )rF   rG   r)   rH   rI   rJ   rK   rL   )rg   r   r   rM   ˜  s    zNumpyDocstring.__init__TFc       	      C   s’   t | jƒ}|r |  |¡\}}}n
|d }}| ¡ | ¡  }}|  |¡}|rX|sX|| }}|  |¡d }|  |  |¡¡}|  || j	¡ 
¡ }|||fS )Nr
   rR   )rW   r1   r`   ry   rd   re   rf   rZ   rg   r(   rP   )	rF   rh   ri   rY   r/   r   rm   rX   rn   r   r   r   rp   Ÿ  s    



zNumpyDocstring._consume_fieldc             C   s   | j ddS )NT)ri   )rr   )rF   r   r   r   rv   °  s    z'NumpyDocstring._consume_returns_sectionc             C   s"   t | jƒ}t |¡st | jƒ |S )N)rW   r1   r­   rb   )rF   r{   r   r   r   r|   ´  s    


z&NumpyDocstring._consume_section_headerc             C   sN   | j  d¡\}}| j  ¡  pL|  ¡ pLddg||gkpL| joL|oL|  || j¡ S )Nr_   r
   )r1   rS   r[   r\   r3   rU   r4   )rF   Zline1Zline2r   r   r   rT   ¼  s    z NumpyDocstring._is_section_breakc             C   sl   | j  d¡\}}| ¡ }|| jkr:t|tƒr:tt |¡ƒS | j	rht
 |¡rhx| j	D ]}| |¡rRdS qRW dS )Nr_   TF)r1   rS   rz   r   r+   r   ÚboolÚ_numpy_section_regexrb   r   r­   r®   )rF   r{   Z	underliner¯   r   r   r   r\   Æ  s    

z!NumpyDocstring._is_section_headerzO^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`| (?P<name2>[a-zA-Z0-9_.-]+))\s*c             C   s4   |   ¡ }y
|  |¡S  tk
r.   |  d|¡S X d S )NrÀ   )ru   Ú _parse_numpydoc_see_also_sectionÚ
ValueErrorrŽ   )rF   r{   rP   r   r   r   rA   Ö  s
    
z&NumpyDocstring._parse_see_also_sectionc                sF  g ‰ ‡fdd„‰‡ ‡fdd„}d}g }x|D ]ú}|  ¡ s<q.ˆj |¡}|r¶|| ¡ d…   ¡  d¡r¶|||ƒ |d| ¡ … || ¡ d…  }}| dd¡d   ¡ g}|d s´g }q.| d	¡s|||ƒ d}d
|krx4| d
¡D ]}|  ¡ ræ||g ƒ qæW n|  ¡ r(|}q.|dk	r.| |  ¡ ¡ q.W |||ƒ ˆ s@g S dddddddddddddddddœ}ˆjdkrxd}	n| ˆjd¡}	g }
d}x ˆ D ]˜\}}}|r²d||f }n|	rÆd|	|f }nd| }|sÚ|rð|
dg7 }
|
|g7 }
n|
d  d| 7  < |r&|
ˆ 	d	 
|¡g¡7 }
d}nd}q”W |
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

        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'rR   NrŠ   r_   z%s is not a item name)Ú	_name_rgxrb   ÚgroupsrÓ   )ÚtextrÈ   Úg)rF   r   r   Úparse_item_nameí  s    zHNumpyDocstring._parse_numpydoc_see_also_section.<locals>.parse_item_namec                s6   | sd S ˆ| ƒ\} }ˆ   | t|ƒ|f¡ |d d …= d S )N)rV   Úlist)rJ   ÚrestÚrole)ÚitemsrØ   r   r   Ú	push_itemù  s
    zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.push_itemNrx   rR   r   r   ú,ÚmethÚfuncr   ÚexcrK   Úmodr´   ÚconstÚattr)Úmethodrß   r   rà   r   Z	exceptionrá   r   rK   r   râ   r´   Zconstantrã   r³   rä   r
   Tz:%s:`%s`z`%s`_r¡   z, %sFrÀ   )ry   rÔ   rb   rÆ   r®   rÂ   rV   r.   r±   r‡   rO   rŽ   )rF   ZcontentrÝ   Zcurrent_funcrÚ   rY   rÈ   rà   ZrolesZ	func_rolerP   Zlast_had_descrˆ   rÛ   Úlinkr   )rÜ   rØ   rF   r   rÒ   Þ  s„    
"






z/NumpyDocstring._parse_numpydoc_see_also_section)NNr
   r
   NN)TF)rÊ   rË   rÌ   rÍ   rM   rp   rv   r|   rT   r\   ÚreÚcompileÚXrÔ   rA   rÒ   Ú__classcell__r   r   )rg   r   rÎ   ;  s   \ 

rÎ   )rÍ   r,   r*   rç   Ú	functoolsr   Zsixr   r   Z	six.movesr   Zsphinx.ext.napoleon.iteratorsr   Zsphinx.localer   Zsphinx.util.pycompatr   rè   r­   r¬   ra   rÑ   rÃ   rÁ   rª   r«   r	   rÎ   r   r   r   r   Ú<module>   s4   	






      