
    Fey                       d Z ddlmZ ddl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mZ ddlmZmZ ddlmZ ddlmZmZ e
rdd	lmZ dd
lmZ  ej4                  e      Z ej:                  d      Z ej:                  d      Z ej:                  d      Z  ej:                  d      Z! ej:                  d      Z" ej:                  d      Z# ej:                  d      Z$ ej:                  d      Z% ej:                  d      Z& ej:                  d      Z' ej:                  d      Z(dZ) G d dejT                        Z+d"d#dZ, G d d      Z-d$dZ.d%dZ/d"d&dZ0	 d'	 	 	 	 	 	 	 d(dZ1 G d  d!e-      Z2y))z-Classes for docstring parsing and formatting.    )annotationsN)partial)TYPE_CHECKINGAnyCallable)___)logging)get_type_hintsstringify_annotation)SphinxConfigz
\.\. \S+::z^(\s|\w)+:\s*$z(.+?)\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z(?<!:):(?!:)zi((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|(?:``.+?``)|(?::meta .+:.*)|(?:`.+?\s*(?<!\x00)<.*?>`))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                  :     e Zd ZdZ e       ZddZd fdZ xZS )Dequez
    A subclass of deque that mimics ``pockets.iterators.modify_iter``.

    The `.Deque.get` and `.Deque.next` methods are added.
    c                @    |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)selfns     ?/usr/lib/python3/dist-packages/sphinx/ext/napoleon/docstring.pygetz	Deque.get=   s!    
 c$i-tAw:T]]:    c                0    | rt         |          S t        N)superpopleftStopIteration)r   	__class__s    r   nextz
Deque.nextD   s    7?$$r   )r   intreturnr   )r&   r   )	__name__
__module____qualname____doc__objectr   r   r$   __classcell__r#   s   @r   r   r   4   s      xH;   r   r   c                0    |	| |v r||    S | dk(  ryd|  dS )z0Convert type specification to reference in reST.r   z:py:obj:`None`z:py:class:`` )_typetranslationss     r   _convert_type_specr3   K   s3    E\$9E""q!!r   c                     e Zd ZdZ ej
                  dej                        Z	 	 	 	 	 	 d=	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d>dZd?dZ	d@dZ
dAdBdZd@dZd@d	ZdC	 dDd
Z	 	 dE	 	 	 dFdZdGdZdH	 dIdZd@dZd?dZd@dZd@dZdHdJdZdKdZdLdZdMdZ	 dN	 	 	 	 	 	 	 dOdZ	 dP	 	 	 	 	 dQdZdRdZ	 	 dSdZdTdUdZdVdZdWdZ dWdZ!dXdYdZ"dAdZdZ#d[d Z$d\d!Z%d\d"Z&d]d#Z'd]d$Z(d^d%Z)d@d&Z*d_d'Z+d_d(Z,d_d)Z-d_d*Z.d_d+Z/d_d,Z0d`d-Z1d_d.Z2d_d/Z3d_d0Z4d_d1Z5d_d2Z6d_d3Z7d_d4Z8d_d5Z9d_d6Z:d_d7Z;d_d8Z<d_d9Z=dad:Z>dbd;Z?dcd<Z@y)dGoogleDocstringaW  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 no_index 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*Nc                   || _         |r|| _        n&|r|j                  | _        nddlm}  |       | _        |s@t        j                  |      rd}n(t        j                  |      rd}nt        |      rd}nd}|| _	        || _
        || _        || _        t        |t              r|j                         }	n|}	t!        t#        t        j$                  |	            | _        g | _        d| _        d| _        t/        | d      sg | _        t/        | d	      s1i d
| j2                  d| j2                  dt5        | j6                  d      d| j8                  dt5        | j6                  d      dt5        | j6                  d      dt5        | j6                  d      d| j:                  d| j:                  dt5        | j6                  d      dt5        | j6                  d      d| j<                  d| j<                  d| j>                  dt5        | j6                  d      d| j@                  d| jB                  i d| j2                  d| jD                  d| jD                  d| jF                  d| jF                  d | jH                  d!| jH                  d"| jJ                  d#| jL                  d$t5        | j6                  d$      d%t5        | j6                  d%      d&t5        | j6                  d&      d't5        | j6                  d&      d(| jN                  d)| jN                  d*| jP                  d+| jP                  | _)        | jU                          | jW                          y ),Nr   r   classmodulefunctionr+   F_directive_sections	_sectionsargs	arguments	attention
attributescautiondangererrorexampleexampleshint	importantzkeyword argszkeyword argumentsmethodsnotenoteszother parameters
parametersreceivereceivesr&   returnsraiseraises
referenceszsee alsotiptodowarningwarningswarnwarnsyieldyields),_app_configconfigsphinx.ext.napoleonr   inspectisclassismodulecallable_what_name_obj_opt
isinstancestr
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_sectionr;   _load_custom_sections_parse)
r   	docstringr[   appwhatnameobjoptionsr   liness
             r   __init__zGoogleDocstring.__init__   s    	!DL::DL2!8DLs#!!#&#!

		i%((*EEC

E23(*# t2324D$t[)#366#3T;;#3 WT%;%;[I#3 d<<	#3
 74#9#99E#3 '$"8"8(C#3 !7!7A#3 477#3 D88#3  6 6?#3 WT%;%;[I#3  E E#3 $T%J%J#3 466#3  6 6?#3  22!#3" #D$H$H##3$ d<<%#3& 477'#3( D88)#3* $55+#3, 466-#3. 33/#30 $441#32 d<<3#34 D885#36 wt55u=7#38  6 6?9#3: 74#9#99E;#3< GD$:$:IF=#3> 11?#3@ 22A#3B 33C#3D $44E#3DNJ 	""$r   c                @    dj                  | j                               S )zReturn the parsed docstring in reStructuredText format.

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

        
)joinr   r   s    r   __str__zGoogleDocstring.__str__   s     yy&&r   c                    | j                   S )zReturn the parsed lines of the docstring in reStructuredText format.

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

        )rk   r   s    r   r   zGoogleDocstring.lines   s     !!!r   c                \   g }| j                   j                  d      }| j                         s~|r| j                  ||      rj|j	                  | j                   j                                | j                   j                  d      }| j                         s|sW| j                  ||      rj|S Nr   )rj   r   _is_section_break_is_indentedappendr$   )r   indentr   lines       r   _consume_indented_blockz'GoogleDocstring._consume_indented_block  s    {{q!&&(**48LL))+,;;??1%D	 &&(**48 r   c                :   g }| j                   r| j                   j                  d      rq| j                         sa|j                  | j                   j	                                | j                   r,| j                   j                  d      r| j                         sa|S r   )rj   r   _is_section_headerr   r$   r   r   s     r   _consume_contiguousz#GoogleDocstring._consume_contiguous  sm    {{{{q!**,LL))+, {{{{q!**,r   c                   g }| j                   j                  d      }| j                   rU|sS|j                  | j                   j                                | j                   j                  d      }| j                   r|sS|S r   )rj   r   r   r$   r   r   r   s      r   _consume_emptyzGoogleDocstring._consume_empty  s_    {{q!kk$LL))+,;;??1%D kk$ r   c                v   | j                   j                         }| j                  |      \  }}}|d|}	}}|rGt        j	                  |      }
|
r0|
j                  d      j                         }|
j                  d      }| j                  |      }|r|s||}}|r:| j                  j                  r$t        || j                  j                  xs i       }| j                  |      dz   }|	g| j                  | j                  |            z   }| j                  || j                        j!                         }|||fS )N       )rj   r$   _partition_field_on_colon_google_typed_arg_regexmatchgroupstrip_escape_args_and_kwargsrZ   napoleon_preprocess_typesr3   napoleon_type_aliases_get_indent_dedentr   r#   r   )r   
parse_typeprefer_typer   beforecolonafterrb   r1   _descr   r   _descss                r   _consume_fieldzGoogleDocstring._consume_field  s   {{!#==dCu$b%eu+11&9EA,,.A,,U3u %5ET\\;;&udll.P.P.VTVWE!!$'!+4<<(D(DV(LMM5;;=eV##r   c                F   | j                          g }| j                         s~| j                  ||      \  }}}|r;|r9|j                  d      D ]$  }|j	                  |j                         ||f       & n|s|s|r|j	                  |||f       | j                         s~|S )N,)r   r   r   splitr   r   )	r   r   r   multiplefieldsrb   r1   r   r   s	            r   _consume_fieldszGoogleDocstring._consume_fields7  s    ((*"&"5"5j+"NE5%E!KK, @DMM4::<">?@%5ueU34 ((* r   c                   | j                   j                         }| j                  |      \  }}}|r|s	||}}||z  }|g| j                  | j	                               z   }| j                  || j                        j                         }||fS r   )rj   r$   r   r   _consume_to_endr#   rZ   r   )r   r   r1   r   r   r   s         r   _consume_inline_attributez)GoogleDocstring._consume_inline_attributeD  s    {{!"<<TBueE %5EUNE4<<(<(<(>??5;;=f}r   c                   | j                  | j                               }|r| j                  |d         \  }}}dd|}}}|r|r
|g|dd  z   }n|dd  }|}|r<|r:| j                  j                  r$t        || j                  j                  xs i       }| j                  || j                        j                         }|||fgS g S )Nr   r   r   )	r   _consume_to_next_sectionr   rZ   r   r3   r   r#   r   )	r   preprocess_typesr   r   r   r   rb   r1   r   s	            r   _consume_returns_sectionz(GoogleDocstring._consume_returns_sectionN  s    T::<=#'#A#A%(#K FE5"$b%%5E"GeABi/E!!"IE*LL::*5$,,2T2T2ZXZ[NN5$,,7==?EE5)**Ir   c                D    | j                  | j                               }|S r   )r   r   r   s     r   _consume_usage_sectionz&GoogleDocstring._consume_usage_sectionf  s    T::<=r   c                    | j                   j                         }|j                  d      }|j                         | j                  v r|}|S )N:)rj   r$   r   lowerr;   )r   sectionstripped_sections      r   _consume_section_headerz'GoogleDocstring._consume_section_headerj  sB    ++""$"==-!!#t~~5&Gr   c                    g }| j                   r6|j                  | j                   j                                | j                   r6|S r   )rj   r   r$   r   s     r   r   zGoogleDocstring._consume_to_endq  s5    kkLL))+, kkr   c                    | j                          g }| j                         s:|j                  | j                  j	                                | j                         s:|| j                         z   S r   )r   r   r   rj   r$   r   s     r   r   z(GoogleDocstring._consume_to_next_sectionw  sZ    ((*LL))+, ((*t**,,,r   c                    |r|D cg c]  }|j                          c}S | j                  |      }|D cg c]  }||d  	 c}S c c}w c c}w r   )lstrip_get_min_indent)r   r   fullr   
min_indents        r   r   zGoogleDocstring._dedent~  sN    .34dDKKM44--e4J278$D%88 5 9s
   AA
c                    |j                  d      rt        | j                  dd      r|d d dz   }|d d dk(  rd|dd  z   S |d d	 d
k(  rd|d	d  z   S |S )Nr   strip_signature_backslashFz\_r   **z\*\*r   *z\*)endswithgetattrrZ   )r   r   s     r   r   z'GoogleDocstring._escape_args_and_kwargs  sq    =='$,,8SUZ"[9u$D8tT!"X%%"1X_48##Kr   c                   | j                  |      rdg|z   }|S |d   j                  d      rQ|dd  }| j                  |d         }| j                  |      }||kD  rdg|z   }|S d|d   g| j	                  |d      z   }|S )Nr   r   ::r      )_is_listr   r   _get_initial_indent_indent)r   desc
desc_blockr   block_indents        r   _fix_field_desczGoogleDocstring._fix_field_desc  s    ==4$;D  !Wd#abJ%%d1g.F33J?Lf$td{  DG}t||J'BBr   c                    | j                  |      }t        |      dk(  rd| d|d   j                          dgS |r/| j                  | j	                  |      d      }d|z  dg|z   dgz   S d|z  dgS )Nr   z.. z:: r   r      z.. %s::)_strip_emptyr   r   r   r   )r   
admonitionr   s      r   _format_admonitionz"GoogleDocstring._format_admonition  s    !!%(u:?*Sq)9(:;R@@LLe!4a8E
*B/%72$>>
*B//r   c                    |rw|dt        |      z  }g }t        |      D ]U  \  }}|dk(  r#|j                  ||z   j                                .|r|j                  ||z          E|j                  d       W |S |gS )N r   r   )r   	enumerater   ri   )r   prefixr   paddingresult_linesir   s          r   _format_blockzGoogleDocstring._format_block  s     F+L$U+ ,46 ''$(>(>(@A ''$7 ''+,  8Or   c           	     B   g }|D ]  \  }}}| j                  |      }t        |      r<| j                  |      }d| d| d}|j                  | j	                  ||             n|j                  d| d| d       |sz|j                  d| d| d|         |dgz   S )Nr   r   : r   )r   anyr   extendr   r   )	r   r   
field_role	type_roler   rb   r1   r   fields	            r   _format_docutils_paramsz'GoogleDocstring._format_docutils_params  s     #) 
	?E5%%%e,E5z,,U3J<qr2T//u=>qAeWA67q1UG2eW=>
	? t|r   c                (   | j                  |      }t        |      }|rdnd}|r'|rd|v rd| d| d| }n-d| d| d| }n!d| d| }n|rd|v r| | }nd	| d	| }nd}|r+| j                  |      }|d
   r||d
   z   g|dd  z   S |g|z   S |gS )Nz -- r   r/   r   z** ()z** (*z*)r   r   r   )r   r   r   )r   rb   r1   r   has_desc	separatorr   s          r   _format_fieldzGoogleDocstring._format_field  s    !!%(u:&FB	%< tE7!I;?E uUG2i[AEUG2i[1e| ')-E7!I;/E((/EQxa()E!"I55w&7Nr   c                   d|j                         z  }dt        |      z  }t        |      dkD  }g }|D ]  \  }}}| j                  |||      }	|rL|r%|j                  | j	                  |dz   |	             C|j                  | j	                  |dz   |	             h|j                  | j	                  |dz   |	              |r|d   r|j                  d       |S )Nz:%s:r   r   z * r   r   )r   r   r   r   r   r   )
r   
field_typer   r   multir   rb   r1   r   r   s
             r   _format_fieldszGoogleDocstring._format_fields  s    j..00
J'Fa#) 	JE5%&&ueU;ELL!3!3GeOU!KLLL!3!3J4F!NOT//
S0@%HI	J U2YLLr   c                   | j                   j                  |      }|| j                   j                  urL|r| j                  |      S |dz  }| j                   j                  |      }|| j                   j                  urLy)Nr   r   )rj   r   r   r   )r   
peek_aheadr   s      r   _get_current_indentz#GoogleDocstring._get_current_indent  sn    {{z*$++...''--!OJ;;??:.D	 $++...
 r   c                f    t        |      D ]  \  }}|j                         r|c S  t        |      S r   )r   isspacer   )r   r   r   ss       r   r   zGoogleDocstring._get_indent  s3    dO 	DAq99;	 4yr   c                <    |D ]  }|s| j                  |      c S  yr   r   r   s      r   r   z#GoogleDocstring._get_initial_indent	  s*     	.D''--	. r   c                \    d }|D ]   }|s| j                  |      }|||k  s|}" |xs dS r   r  )r   r   r   r   r   s        r   r   zGoogleDocstring._get_min_indent  sG    
 	(D))$/%*)<!'J		(
 Qr   c                8    |D cg c]
  }d|z  |z    c}S c c}w )Nr   r0   )r   r   r   r   s       r   r   zGoogleDocstring._indent  s    -23TqD 333s   c                \    t        |      D ]  \  }}||k\  r y|j                         r y yNTF)r   r  )r   r   r   r   r  s        r   r   zGoogleDocstring._is_indented  s4    dO 	DAqF{YY[		
 r   c                .   |syt         j                  |d         ryt        j                  |d         ryt        |      dk  s|d   j	                  d      ry| j                  |d         }|}|dd  D ]  }|s| j                  |      } ||kD  S  ||kD  S )NFr   Tr   r   r   )_bullet_list_regexr   _enumerated_list_regexr   r   r   )r   r   r   next_indentr   s        r   r   zGoogleDocstring._is_list#  s    ##E!H-!''a1u:>U1X..t4!!%(+!"I 	D"..t4V##		 V##r   c                   | j                   j                  d      j                         }t        j	                  |      }|rE|j                  d      | j                  v r(| j                  |      }| j                  d      }||kD  S | j                  r9t        j	                  |      r$| j                  D ]  }|j                  |      s y y)Nr   r   r   )r   TF)rj   r   r   _google_section_regexr   r   r;   r   r   r:   _directive_regex
startswith)r   r   r   header_indentsection_indentdirective_sections         r   r   z"GoogleDocstring._is_section_header4  s    ++//!$**,%++G4W]]3'4>>9 ,,W5M!555CN!M11%%%%g.)-)A)A $%))*;<#$ r   c                    | j                   j                  d      }| j                    xsA | j                         xs/ | j                  xr! |xr | j	                  || j
                         S r   rj   r   r   rl   r   rm   )r   r   s     r   r   z!GoogleDocstring._is_section_breakB  sl    {{q!KK G'')G$$ FF))$0D0DEE		Hr   c                P   | j                   j                  | j                   j                  D ]  }t        |t              r(| j                  | j
                  |j                         <   ;|d   dk(  r+| j                  | j
                  |d   j                         <   n|d   dk(  r+| j                  | j
                  |d   j                         <   | j
                  j                  |d   j                         | j                        | j
                  |d   j                         <    y y )Nr   params_styler   returns_style)
rZ   napoleon_custom_sectionsre   rf   _parse_custom_generic_sectionr;   r   "_parse_custom_params_style_section#_parse_custom_returns_style_sectionr   )r   entrys     r   r~   z%GoogleDocstring._load_custom_sectionsJ  s    <<00<>> SeS) 594V4VDNN5;;=1 Qx>1 CC uQx~~'78q_4 DD uQx~~'78 !NN..uQx~~/?/3/Q/QS uQx~~'78!S =r   c                \   | j                         | _        | j                  r^| j                  dv rPg }t	        j
                  t              5  | j                         }d d d        | j                  j                  |       y | j                  r | j                         r	 | j                         }d| _        | j                         | _        t        j!                  |      r|g| j#                         z   }n# | j$                  |j'                            |      }d| _        d| _        n>| j                  s"| j)                         | j                         z   }n| j#                         }| j                  j                  |       | j                  ry y # 1 sw Y   4xY w# d| _        d| _        w xY w)N)	attributedatapropertyTFr   )r   rk   rb   ra   
contextlibsuppressr"   _parse_attribute_docstringr   rj   r   r   rl   r   rm   r  r   r   r;   r   r   )r   resr   r   s       r   r   zGoogleDocstring._parse`  se   !002::$**(IIC$$]3 85578 %%c*kk&&(
-"::<G*.D'+/+C+C+ED('--g6!(	D,I,I,K K ?w}} ? H*/D'+,D()) 4469L9L9NNE 99;E%%e,% kk8 8" +0D'+,D(s   FA9F FF+c                F    | j                         }| j                  ||      S r   )r   r   )r   r   r   r   s       r   rp   z!GoogleDocstring._parse_admonition  s#    --/&&z599r   c                    | j                         \  }}| j                  dd|      }|r|j                  dd|z  g       |S )Nr   	:type: %s)r   r   r   )r   r1   r   r   s       r   r%  z*GoogleDocstring._parse_attribute_docstring  sF    557u""2r51LL"kE123r   c                   g }| j                         D ]L  \  }}}|s| j                  |      }| j                  j                  rAd|z  }|j	                  | j                  ||             |sZ|j                  d| d|        r|j                  d|z          | j                  r-d| j                  v sd| j                  v r|j                  d       |j                  d       | j                  dd|      }|j	                  | j                  |d	             |r6|j                  d       |j	                  | j                  d
|z  gd	             |j                  d       O | j                  j                  r|j                  d       |S )Nz
:ivar %s: z	:vartype r   z.. attribute:: no-indexnoindex   :no-index:r   r   r)  )
r   _lookup_annotationrZ   napoleon_use_ivarr   r   r   rd   r   r   )r   r   r   rb   r1   r   r   r   s           r   rq   z)GoogleDocstring._parse_attributes_section  sR   #'#7#7#9 	!E5%//6||--$u,T//u=>LL9UG2eW!=>.6799!TYY.)tyy2H_5R ++BE:T\\&!45LL$LL{U/B.CQ!GHR )	!* <<))LLr   c                    t        d      t        d      d}| j                  j                  }|j                  |j	                         |      }| j                  ||      S )NExampleExamples)rC   rD   )r   rZ   $napoleon_use_admonition_for_examplesr   r   _parse_generic_section)r   r   labelsuse_admonitionlabels        r   rr   z'GoogleDocstring._parse_examples_section  sQ    |*
 JJ

7==?G4**5.AAr   c                &    | j                  |d      S )NF)r4  r   r   s     r   r  z-GoogleDocstring._parse_custom_generic_section  s    **7E::r   c                B    | j                  || j                               S r   )r   r   r9  s     r   r  z2GoogleDocstring._parse_custom_params_style_section  s    ""7D,@,@,BCCr   c                J    | j                  d      }| j                  ||      S )NTr   )r   r   r   r   r   s      r   r  z3GoogleDocstring._parse_custom_returns_style_section  s(    ...E""7F33r   c                n    ddg}ddg}| j                         }| j                  |d      }||z   |z   dgz   S )Nz.. rubric:: Usage:r   z.. code-block:: pythonr   )r   r   )r   r   headerblockr   s        r   _parse_usage_sectionz$GoogleDocstring._parse_usage_section  sJ    &+)2.++-UA&~%,,r   c                    | j                  | j                               }| j                  |      }|rd|z  }| j                  |d      }nd|z  }|r|dg|z   dgz   S |dgS )Nz.. admonition:: %sr   z.. rubric:: %sr   )r   r   r   r   )r   r   r6  r   r?  s        r   r4  z&GoogleDocstring._parse_generic_section  ss    !!$"?"?"ABU#)G3FLL*E%/FB<%'2$..B<r   c                    | j                         }| j                  j                  r| j                  |dd      S | j	                  t        d      |      S )Nkeywordkwtype)r   r   zKeyword Arguments)r   rZ   napoleon_use_keywordr   r   r   r=  s      r   rs   z0GoogleDocstring._parse_keyword_arguments_section  sY    %%'<<,,//$" 0 $ $
 &&q)<'=vFFr   c                J   g }| j                  d      D ]  \  }}}|j                  d|z         | j                  r-d| j                  v sd| j                  v r|j                  d       |r%|j                  dg| j	                  |d      z          |j                  d        |S )	NF)r   z.. method:: %sr+  r,  r-  r   r   )r   r   rd   r   r   )r   r   r   rb   r1   r   s         r   rt   z&GoogleDocstring._parse_methods_section  s    #'#7#75#7#I 	E5%LL)E12yy*i499.DLL1bTDLL$::;LL	 r   c                d    | j                   j                  }| j                  t        d      |      S )NNotes)rZ   !napoleon_use_admonition_for_notesr4  r   r   r   r6  s      r   ru   z$GoogleDocstring._parse_notes_section  s(    GG**1W:~FFr   c                    | j                   j                  r#| j                  d      }| j                  |      S | j                         }| j	                  t        d      |      S )NTr   zOther ParametersrZ   napoleon_use_paramr   r   r   r   r=  s      r   rv   z/GoogleDocstring._parse_other_parameters_section  sZ    <<**))4)8F//77))+F&&q);'<fEEr   c                    | j                   j                  r#| j                  d      }| j                  |      S | j                         }| j	                  t        d      |      S )NTrM  
ParametersrN  r=  s      r   ro   z)GoogleDocstring._parse_parameters_section  sX    <<**))4)8F//77))+F&&q??r   c                   | j                  dd      }g }|D ]  \  }}}| j                  j                  |      }|r#|j                  d      r|j                  d      }n.t        j                  |      r|j                  d      }||dz   d }|rd|z   nd	}| j                  |      }t        |      rdd
j                  |      z   nd	}	|j                  d| d|	         |r|j                  d	       |S )NFT)r   r   r   r/   r   r   r   r   z
    z:raisesr   )
r   	_name_rgxr   r   _xref_regexfindr   r   r   r   )
r   r   r   r   rb   r1   r   mposr   s
             r   ry   z%GoogleDocstring._parse_raises_section  s    %%D%I#) 
	5E5%$$U+AQWWV_""5)jjocAgb)#(C%KbE%%e,E36u:S8==//2FLL75'6(34
	5 LLr   c                    | j                   j                  r#| j                  d      }| j                  |      S | j                         }| j	                  t        d      |      S )NTrM  ReceivesrN  r=  s      r   rw   z'GoogleDocstring._parse_receives_section  sX    <<**))4)8F//77))+F&&q}f==r   c                d    | j                   j                  }| j                  t        d      |      S )N
References)rZ   &napoleon_use_admonition_for_referencesr4  r   rK  s      r   rz   z)GoogleDocstring._parse_references_section  s(    LL**1\?NKKr   c                2   | j                         }t        |      dkD  }|rdn| j                  j                  }g }|D ]  \  }}}|r| j	                  |d|      }	n| j	                  |||      }	|rF|r"|j                  | j                  d|	             V|j                  | j                  d|	             xt        |	      r!|j                  | j                  d|	             |s|s|j                  d|z  dg        |r|d   r|j                  d       |S )	Nr   Fr   z          * z:returns: * z
:returns: z
:rtype: %sr   )	r   r   rZ   napoleon_use_rtyper   r   r   r   r   )
r   r   r   r   	use_rtyper   rb   r1   r   r   s
             r   rx   z&GoogleDocstring._parse_returns_section  s   ..0Fa"E(G(G	#) 	=E5%**5"e<**5%?LL!3!3NE!JKLL!3!3NE!JKu:LL!3!3L%!HIYLL,"6!;<	=  U2YLLr   c                &    | j                  d|      S Nseealso)rp   r9  s     r   r{   z'GoogleDocstring._parse_see_also_section3  s    %%i99r   c                T    | j                  t        d      | j                               S )NWarns)r   r   r   r9  s     r   r|   z$GoogleDocstring._parse_warns_section6  s"    ""1W:t/C/C/EFFr   c                \    | j                  d      }| j                  t        d      |      S )NTr<  Yields)r   r   r   r=  s      r   r}   z%GoogleDocstring._parse_yields_section9  s,    ...E""1X;77r   c                4   g }g }d}d}t        t        j                  |            D ]  \  }}|r|j                  |       t        j                  |      }|dz  dk(  rj|rhd}||j                         |j                          }|j                  |d |j                                 |j                  ||j                         d         |j                  |        dj                  |      j                         |dj                  |      j                         fS )Nr   Fr   r   T)
r   _xref_or_code_regexr   r   _single_colon_regexsearchstartendr   r   )	r   r   before_colonafter_colonr   found_colonr   sourcerV  s	            r   r   z)GoogleDocstring._partition_field_on_colon=  s   "#6#<#<T#BC 	0IAv""6*'..v6Ea<A"&K"1779aeeg6E ''z	(:;&&vaeegh'78 ''/	0 %++-$**,. 	.r   c                    |rod}t        |      D ]  \  }}|s	|} n |dk(  rg }d}t        t        t        |                  D ]  }||   }|s|} n |dkD  s|dz   t        |      k  r|||dz    }|S )Nr   r   r   )r   reversedranger   )r   r   rk  r   r   rl  s         r   r   zGoogleDocstring._strip_emptyS  s    E$U+ 4E {CeCJ/0 QxC	
 qyC!Gc%j0eC!G,r   c                   | j                   j                  r| j                  dv r| j                  rt	        | d      s]t        | j                   di       }|j                  t        | j                   di       xs i        t        | j                  d |      | _        || j                  v rt        | j                  |   d      S y)N)r8   r7   	exception_annotationsautodoc_type_aliasesr   zfully-qualified-except-typingr   )
rZ   napoleon_attr_annotationsra   rc   rn   r   updater   rv  r   )r   rb   localnss      r   r.  z"GoogleDocstring._lookup_annotationf  s    <<11zz==$))t^4%dll4JBOGNN7#'<<1H"$% $+(*, )7tyy$(PD%D---/0A0A%0H0OQ Q r   NNr   r   NNr   zstr | list[str]r[   zSphinxConfig | Noner   zSphinx | Noner   rf   r   rf   r   r   r   r   r&   r   r&   rf   )r&   	list[str])r   )r   r%   r&   r~  TFr   boolr   r  r&   ztuple[str, str, list[str]])TFF)r   r  r   r  r   r  r&    list[tuple[str, str, list[str]]])r&   ztuple[str, list[str]]Fr   r  r&   r  )r   r~  r   r  r&   r~  r   rf   r&   rf   )r   r~  r&   r~  )r   rf   r   r~  r&   r~  r   )r   rf   r   r~  r   
str | Noner&   r~  )paramtype)r   r  r   rf   r   rf   r&   r~  )rb   rf   r1   rf   r   r~  r&   r~  )r   rf   r   r  r&   r~  )r   )r   r%   r&   r%   )r   rf   r&   r%   )r   r~  r&   r%   )r   )r   r~  r   r%   r&   r~  )r   rf   r   r%   r&   r  )r   r~  r&   r  r&   r  )r&   r   )r   rf   r   rf   r&   r~  r   rf   r&   r~  )r   rf   r6  r  r&   r~  )r   rf   r&   ztuple[str, str, str])r   r~  r&   r~  )rb   rf   r&   rf   )Ar'   r(   r)   r*   recompileXrS  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   r~   r   rp   r%  rq   rr   r  r  r  rA  r4  rs   rt   ru   rv   ro   ry   rw   rz   rx   r{   r|   r}   r   r   r.  r0   r   r   r5   r5   T   s3   <| 

 @ACGI '+!T"T $T 	T
 T T T T 
Tl	'	"	$6$4 LQ)."&3S&F0-9	0 DH"+6@	& MS,/FI%.":%&4$"HS,->:
6B;D4- G
GF@$>L4:G8.,&r   r5   c                j    t        j                  |       }dfdfd}t         ||            S )Noptionaldefaultc              3  *  K   d}d }	 	 | j                         }|dk(  r|}|j                         s+|v r%| j                  |       || j                  |       y || d }|dk(  r|dz  }n
|dk(  r|dz  }| |dk(  ry {# t        $ r Y y w xY ww)Nr   , {r   })r!   
IndexErrorr   
appendleft)tokensopen_bracesprevious_tokentokenkeywordss       r   takewhile_setz,_recombine_set_tokens.<locals>.takewhile_set{  s     ( }!&;;= !!%(!-%%n5)$$!%|q #q Ka?   s(   BB A*B	BBBBc              3     K   	 	 | j                         }|dk(  r+| j                  d       dj                   |              n| F# t        $ r Y y w xY ww)Nr  r   )r!   r  r  r   )r  r  r  s     r   combine_setz*_recombine_set_tokens.<locals>.combine_set  sc     ( |!!#&ggmF344   s'   AA 5A	AAAA)collectionsdequelist)r  token_queuer  r  r  s      @@r   _recombine_set_tokensr  w  s5    ##F+K&H"H K())r   c                ~    d }t         j                  |       D cg c]  } ||      D ]  }|r|  }}}|S c c}}w )Nc                P    t         j                  |       r| d d }| dd  }|d|gS | gS )N      r   )_default_regexr   )itemr  others      r   postprocessz(_tokenize_type_spec.<locals>.postprocess  s<    %2AhG HES%((6Mr   )_token_regexr   )specr  	raw_tokenr  r  s        r   _tokenize_type_specr    sZ    	 &++D1	*  	F  Ms   9c                2   d }| j                  d      s| j                  d      rd}|S  ||       sf| j                  d      r| j                  d      sD| j                  d      r| j                  d      s"| j                  d      r| j                  d      rd}|S | j                  d      r%t        j                  t	        d	      | |
       d}|S | j                  d      r%t        j                  t	        d      | |
       d}|S | j                  d      r%t        j                  t	        d      | |
       d}|S | j                  d      r%t        j                  t	        d      | |
       d}|S | dv rd}|S t
        j                  |       rd}|S d}|S )Nc                :    	 t        |        y# t        $ r Y yw xY wr	  )complex
ValueError)r  s    r   
is_numericz_token_type.<locals>.is_numeric  s'    	EN   		s    	r   	delimiterr  r  "'literalz-invalid value set (missing closing brace): %s)locationz-invalid value set (missing opening brace): %s)r  r  z4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %sr  control	referencer   )r  r   loggerrS   r	   rT  r   )r  r  r  type_s       r   _token_typer    s    s 3Z LW uc"u~~c':c"u~~c':c"u~~c':L LK 
		#	>? 	 	

 > L= 
	>? 	 	

 0 L/ 
		*	%EF 	 	

 " L! 

	#EF 	 	

  L 
)	)  L 
		5	! L Lr   c                   	 i d t        |       }t        |      }|D cg c]  }|t        ||      f }}d fdd d d d	dj                  	fd	|D              }|S c c}w )
Nc                    |j                  | |       }|t        v r|dk(  rd}n|dk(  r|dk(  rd}t        j                  |      ||z  }|S )N:class:`%s`	:obj:`%s`z...z:obj:`%s <Ellipsis>`)r   _SINGLETONSrT  r   )r   r2   default_translationtranslations       r   convert_objz-_convert_numpy_type_spec.<locals>.convert_obj  sc    "&&sC0 +%*=*N"-E!&9]&J"8[)1-;Kr   c                    d| z  S )Nz``%s``r0   xs    r   <lambda>z*_convert_numpy_type_spec.<locals>.<lambda>  s
    X\ r   c                     | d      S )Nr  r0   )r  r  r2   s    r   r  z*_convert_numpy_type_spec.<locals>.<lambda>  s    QmD r   c                    d| z  S )Nz*%s*r0   r  s    r   r  z*_convert_numpy_type_spec.<locals>.<lambda>  s
    VaZ r   c                    | S r   r0   r  s    r   r  z*_convert_numpy_type_spec.<locals>.<lambda>      q r   c                    | S r   r0   r  s    r   r  z*_convert_numpy_type_spec.<locals>.<lambda>   r  r   )r  r   r  r  r  r   c              3  R   K   | ]  \  }} j                  |      |         y wr   )r   ).0r  r  
converterss      r   	<genexpr>z+_convert_numpy_type_spec.<locals>.<genexpr>#  s-      3(E5 .
u-e4 3s   $')r  r  r  r   )
r1   r  r2   r  combined_tokensr  types	convertedr  r  s
     `     @@r   _convert_numpy_type_specr    s      !'F+F3O % 
E8,-E  *D'  J  3,13 3I !s   A(c                       e Zd ZdZ	 	 	 	 	 	 d	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d fdZddZd fdZd	 ddZd	 ddZddZ	ddZ
dd	Zdd
ZddZ x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 no_index 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.

    c           	     @    dg| _         t        | 	  |||||||       y )Nz
.. index::)r:   r    r   )	r   r   r[   r   r   r   r   r   r#   s	           r   r   zNumpyDocstring.__init__  s(     %1> FCtS'Jr   c                    	 | j                   t        j                  | j                         nd }| j                  }||y |d}dj                  |d|z  g      S # t        $ r d }Y 8w xY w)Nr   r   zdocstring of %s)rc   r]   getfile	TypeErrorrb   r   )r   filepathr   s      r   _get_locationzNumpyDocstring._get_location  sx    	59YY5Jwtyy1PTH zzHxx#4t#;<==  	H	s   -A A('A(c                    t         |   d|v r)dj                  fd|j                  d      D              S  |      S )Nr  c              3  .   K   | ]  } |        y wr   r0   )r  r  funcs     r   r  z9NumpyDocstring._escape_args_and_kwargs.<locals>.<genexpr>  s     GUT%[Gs   )r    r   r   r   )r   r   r  r#   s     @r   r   z&NumpyDocstring._escape_args_and_kwargs  s<    w.4<99Gdjj6FGGG:r   c                d   | j                   j                         }|r| j                  |      \  }}}n|d}}|j                         |j                         }}| j	                  |      }|r|s| j                  |      }|r|s||}}| j                  j                  r4t        || j                         | j                  j                  xs i       }| j                  |      dz   }| j                  | j                  |            }| j                  || j                        j                         }|||fS )Nr   )r  r2   r   )rj   r$   r   r   r   r.  rZ   r   r  r  r   r   r   r   r#   r   )	r   r   r   r   rb   r   r1   r   r   s	            r   r   zNumpyDocstring._consume_field  s   {{!"<<TBOE1e5E{{}ekkmu,,U3e++E2Eu %5E<<11,++-!\\??E2E !!$'!+T99&ABudll399;eU""r   c                &    | j                  d      S )NT)r   )r   )r   r   s     r   r   z'NumpyDocstring._consume_returns_section  s    ###55r   c                    | j                   j                         }t        j                  |      s| j                   j                          |S r   )rj   r$   r  r   r9  s     r   r   z&NumpyDocstring._consume_section_header  s7    ++""$%%g.KKr   c                $   | j                   j                  d      | j                   j                  d      }}| j                    xsL | j                         xs: ddg||gk(  xs/ | j                  xr! |xr | j	                  || j
                         S )Nr   r   r   r  )r   line1line2s      r   r   z NumpyDocstring._is_section_break  s    {{q)4;;??1+=uKK H'')HRUEN*H $$ GG))%1E1EFF	Ir   c                   | j                   j                  d      | j                   j                  d      }}|j                         }|| j                  v r.t	        |t
              rt        t        j                  |            S | j                  r9t        j                  |      r$| j                  D ]  }|j                  |      s y y)Nr   r   TF)rj   r   r   r;   re   rf   r  _numpy_section_regexr   r:   r  r  )r   r   	underliner  s       r   r   z!NumpyDocstring._is_section_header  s    ![[__Q/1C--/dnn$Is)C,229=>>%%%%g.)-)A)A $%))*;<#$ r   c                    | j                         }	 | j                  |      S # t        $ r | j                  d|      cY S w xY wra  )r    _parse_numpydoc_see_also_sectionr  r   )r   r   r   s      r   r{   z&NumpyDocstring._parse_see_also_section  sH    --/	=88?? 	=**9e<<	=s   # A Ac           
     D    g d fddfd} fd}d}g }|D ]H  }|j                         s j                  j                  |      }|r||j                         d j                         j	                  d      r\ |||       |d|j                          ||j                         d }}|j                  dd      d   j                         g}|d   rg }|j	                  d      sW |||       d}d	|v r2|j                  d	      D ]  }|j                         s ||g         |j                         s"|}&|*|j                  |j                                K  |||       sg S D 	
cg c]  \  }}	}
 |||	|
       c}
}	}g }d
}D ]c  \  }}}
|
r
d|
 d| d}nd|z  }|s|r|dgz  }||gz  }n|dxx   d|z  z  cc<   |r'| j                  dj                  |      g      z  }d
}bd}e |dgz  } j                  d|      S c c}
}	}w )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                    j                   j                  |       }|r&|j                         }|d   |d   dfS |d   |d   fS t        d| z        )zMatch ':role:`name`' or 'name'r   Nr   r   z%s is not a item name)rS  r   groupsr  )textrV  gr   s      r   parse_item_namezHNumpyDocstring._parse_numpydoc_see_also_section.<locals>.parse_item_name  s_    $$T*AHHJQ4<Q4:%Q41:%4t;<<r   c                f    | sy  |       \  } }j                  | t        |      |f       |d d = y r   )r   r  )r   restroleitemsr  s      r   	push_itemzBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.push_item  s5    (.JD$LL$T
D12Qr   c                    j                   j                  }||s| ||fS |j                  | |       }j                  j	                  |      }|s|||fS |j                         }|d   }|d   xs |d   }|||fS )Nr  r   name2)rZ   r   r   rS  r   	groupdict)	r  descriptionr  r2   
translatedr   r  new_funcr   s	           r   	translatezBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.translate  s    <<==L|[$..%))$5JNN((4E!;44__&F&>Df~8H[$..r   Nr   r   r   r   r   Tz:`r/   r  r   r   z, %sFrb  )r  rf   r&   ztuple[str, str | None])r   r  r  r~  r&   r   )
r   rS  r   rl  r  r   r   r   r   r   )r   contentr  r   current_funcr  r   rV  r  r  r  r   last_had_descr   r   linkr  r  s   `               @@r   r  z/NumpyDocstring._parse_numpydoc_see_also_section  sG    		=		/   	*D::<$$T*AT!%%'(^))+66s;,-%)(1557^T!%%'(^d

3*1-3356AwD__S),-#$; $

3 0::<%dB/0 ZZ\#'L)DJJL)+	*, 	,%I
 ,1
 
'k4 dK.

  % 	&D$4&4&*"T)}"$b	Vd]*	sxx~&677 $ %	& 	"&&y%881
s   =H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,   r-   s   @r   r  r  )  s    [~ '+!K"K $K 	K
 K K K K 
K>#6#86&F6I
=g9r   r  r   )r1   rf   r2   zdict[str, str] | Noner&   rf   )r  r~  r&   r~  )r  rf   r&   r~  )r  rf   r  r  r&   rf   )NN)r1   rf   r  r  r2   zdict | Noner&   rf   )3r*   
__future__r   r  r#  r]   r  	functoolsr   typingr   r   r   sphinx.localer   r	   sphinx.utilr
   sphinx.util.typingr   r   sphinx.applicationr   sphinx.configr   SphinxConfig	getLoggerr'   r  r  r  r  r   r  ri  rh  rT  r  r  r  r  r  r  r   r3   r5   r  r  r  r  r  r0   r   r   <module>r     s   3 "    	  / /   C)4			8	$2::m, "

#45 $"**%AB !rzz"@A  bjj1  bjj#$ 
 bjj<  RZZ :; ##$  rzz  4 K  ."` `F5*p*8x JN''$';F''Tj9_ j9r   