| Server IP : 127.0.0.1 / Your IP : 216.73.216.109 Web Server : Apache/2.4.54 (Win64) OpenSSL/1.1.1q PHP/8.1.10 System : Windows NT DESKTOP-E5T4RUN 10.0 build 19045 (Windows 10) AMD64 User : SERVERWEB ( 0) PHP Version : 8.1.10 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/cygwin64/lib/python3.9/site-packages/sphinx/ext/napoleon/__pycache__/ |
Upload File : |
a
�ab�� � @ s� d Z ddlZddlZddlZddlmZ ddlmZmZm Z m
Z
m Z m Z m
Z
ddlmZ ddlmZ ddlmZ ddlmZmZ dd lmZ dd
lmZ dd l 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,dZ-i fe.e e.e.f e.d�dd�Z/G dd � d �Z0e
e. e
e. d �d d �Z1e.e
e. d �d!d"�Z2d+e.e.e.d#�d$d%�Z3di fe.e.e4e.d&�d'd(�Z5G d)d*� d*e0�Z6dS ),z�
sphinx.ext.napoleon.docstring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Classes for docstring parsing and formatting.
:copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
� N)�partial)�Any�Callable�Dict�List�Tuple�Type�Union)�Sphinx��Config)� modify_iter)�_�__)�logging)�stringify_annotation)�get_type_hintsz
\.\. \S+::z^(\s|\w)+:\s*$z(.+?)\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z (?<!:):(?!:)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�Ellipsis)�_type� translations�returnc C s( | |v r|| S | dkr dS d| S | S )z0Convert type specification to reference in reST.r z :obj:`None`� :class:`%s`� )r r r r �A/usr/lib/python3.9/site-packages/sphinx/ext/napoleon/docstring.py�_convert_type_spec9 s r c
@ s e Zd ZdZe�dej�Zd�ee e
e f e e e e e
e
dd�dd�Ze d�d d
�Ze
e d�d d �Zd�ee
e d�dd�Ze
e d�dd�Ze
e d�dd�Zd�eeee e e
e f d�dd�Zd�eeee
ee e e
e f d�dd �Zee e
e f d�d d �Zd�ee
ee e e
e f d �d d!�Ze
e d�d"d#�Ze d�d$d%�Z e
e d�d&d'�Z e
e d�d(d)�Z d�e
e ee
e d*�d+d,�Z e e d-�d.d/�Z e
e e
e d0�d1d2�Z!e e
e e
e d3�d4d5�Z"d�e e
e e e
e d6�d7d8�Z#d�e
ee e e
e f e e e
e d;�d<d=�Z$e e e
e e
e d>�d?d@�Z%e e
ee e e
e f e
e dA�dBdC�Z&d�eedE�dFdG�Z'e edH�dIdJ�Z(e
e edK�dLdM�Z)e
e edK�dNdO�Z*d�e
e ee
e dQ�dRdS�Z+d�e eedT�dUdV�Z,e
e edK�dWdX�Z-ed�dYdZ�Z.ed�d[d\�Z/dd�d]d^�Z0dd�d_d`�Z1e e e
e da�dbdc�Z2e
e d�ddde�Z3e e
e df�dgdh�Z4e e
e df�didj�Z5e e
e df�dkdl�Z6e e
e df�dmdn�Z7e e
e df�dodp�Z8e e
e df�dqdr�Z9e ee
e ds�dtdu�Z:e e
e df�dvdw�Z;e e
e df�dxdy�Z<e e
e df�dzd{�Z=e e
e df�d|d}�Z>e e
e df�d~d�Z?e e
e df�d�d��Z@e e
e df�d�d��ZAe e
e df�d�d��ZBe e
e df�d�d��ZCe e
e df�d�d��ZDe e
e df�d�d��ZEe e
e df�d�d��ZFe ee e e f dH�d�d��ZGe eHe d��d�d��ZIe
e e
e dK�d�d��ZJe e d��d�d��ZKdS )��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� �� docstring�config�app�what�name�obj�optionsr c
# C s� || _ || _| j s4ddlm} | jr,| jjn|� | _ |sjt�|�rHd}n"t�|�rXd}nt|�rfd}nd}|| _ || _
|| _ || _ t
|t�r�|�� } n|} t| dd� d �| _g | _d
| _d| _t| d �s�g | _t| d ��s�| j| jt| jd
�| jt| jd�t| jd�t| jd�| j| jt| jd�t| jd�| j | j | j t| jd�| j | j | j| j | j | j!| j!| j"| j"| j#| j$t| jd�t| jd�t| jd�t| jd�| j%| j%| j&| j&d�"| _'| �(� | �)� d S )Nr r �class�module�function�objectc S s | � � S �N)�rstrip)�sr r r �<lambda>� � z*GoogleDocstring.__init__.<locals>.<lambda>)�modifierF�_directive_sections� _sections� attention�caution�danger�error�hint� important�note�tip�todo�warning)"�argsZ argumentsr4 Z
attributesr5 r6 r7 �example�examplesr8 r9 z keyword argszkeyword arguments�methodsr: Znoteszother parameters�
parametersZreceiveZreceivesr �returns�raiseZraisesZ
referenceszsee alsor; r< r= �warnings�warnZwarns�yieldZyields)*�_configZ_appZsphinx.ext.napoleonr r" �inspectZisclassZismodule�callable�_what�_name�_obj�_opt�
isinstance�str�
splitlinesr
�
_line_iter�
_parsed_lines�_is_in_section�_section_indent�hasattrr2 �_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_sectionr3 �_load_custom_sections�_parse)
�selfr! r" r# r$ r% r& r' r �linesr r r �__init__� s�
�%zGoogleDocstring.__init__�r c C s d� | �� �S )z�Return the parsed docstring in reStructuredText format.
Returns
-------
unicode
Unicode version of the docstring.
�
)�joinri �rh r r r �__str__� s zGoogleDocstring.__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.
)rS rn r r r ri � s zGoogleDocstring.lines� )�indentr c C sF g }| j �� }| �� sB|r&| �||�rB|�t| j �� | j �� }q|S r, )rR �peek�_is_section_break� _is_indented�append�next)rh rq ri �liner r r �_consume_indented_block� s
�
� z'GoogleDocstring._consume_indented_blockc C s6 g }| j �� r2| j �� r2| �� s2|�t| j �� q|S r, )rR �has_nextrr �_is_section_headerru rv �rh ri r r r �_consume_contiguous� s
��z#GoogleDocstring._consume_contiguousc C s< g }| j �� }| j �� r8|s8|�t| j �� | j �� }q|S r, )rR rr ry ru rv �rh ri rw r r r �_consume_empty� s
z GoogleDocstring._consume_emptyTF��
parse_type� prefer_typer c
C s� t | j�}| �|�\}}}|d| }}} |rTt�|�}
|
rT|
�d��� }|
�d�}| �|�}|rp|sp|| }}|r�| jj r�t
|| jj p�i �}| � |�d } | g| �
| �| �� } | �| | j��� } ||| fS )Nr rp � )rv rR �_partition_field_on_colon�_google_typed_arg_regex�match�group�strip�_escape_args_and_kwargsrH �napoleon_preprocess_typesr �napoleon_type_aliases� _get_indent�_dedentrx � __class__ri )
rh r� r� rw �before�colon�afterrL r �_descr� rq �_descsr r r �_consume_field s"
z GoogleDocstring._consume_field)r� r� �multipler c C sv | � � g }| �� sr| �||�\}}}|rT|rT|�d�D ]}|�|�� ||f� q8q |s`|s`|r |�|||f� q |S )N�,)r~ rs r� �splitru r� ) rh r� r� r� �fieldsrL r r� r% r r r �_consume_fields s z GoogleDocstring._consume_fieldsc C sb t | j�}| �|�\}}}|r"|s4|| }}||7 }|g| �| �� � }| �|| j��� }||fS r, )rv rR r� r� �_consume_to_endr� rH ri )rh rw r r� r� r� r r r �_consume_inline_attribute* s
z)GoogleDocstring._consume_inline_attribute��preprocess_typesr c C s� | � | �� �}|r�| �|d �\}}}dd| }}}|rb|rR|g|dd � }n |dd � }|}|r�|r�| jjr�t|| jjp�i �}| �|| j��� }|||fgS g S d S )Nr r rp ) r� �_consume_to_next_sectionr� rH r� r r� r� ri ) rh r� ri r� r� r� rL r r� r r r �_consume_returns_section4 s � z(GoogleDocstring._consume_returns_sectionc C s | � | �� �}|S r, )r� r� r{ r r r �_consume_usage_sectionL s z&GoogleDocstring._consume_usage_sectionc C s* t | j�}|�d�}|�� | jv r&|}|S )N�:)rv rR r� �lowerr3 )rh �sectionZstripped_sectionr r r �_consume_section_headerP s
z'GoogleDocstring._consume_section_headerc C s$ g }| j �� r |�t| j �� q|S r, )rR ry ru rv r{ r r r r� W s
z GoogleDocstring._consume_to_endc C s2 | � � g }| �� s&|�t| j�� q || � � S r, )r~ rs ru rv rR r{ r r r r� ] s
z(GoogleDocstring._consume_to_next_section)ri �fullr c s2 |rdd� |D �S | � |�� � fdd�|D �S d S )Nc S s g | ] }|� � �qS r )�lstrip��.0rw r r r �
<listcomp>f r0 z+GoogleDocstring._dedent.<locals>.<listcomp>c s g | ]}|� d � �qS r, r r� ��
min_indentr r r� i r0 )�_get_min_indent)rh ri r� r r� r r� d s
zGoogleDocstring._dedent�r% r c C sp |� d�r(t| jdd�r(|d d� d }|d d� dkrHd|dd � S |d d � d
krhd |d d � S |S d S ) Nr Zstrip_signature_backslashF���z\_r� z**z\*\*rp �*z\*)�endswith�getattrrH �rh r% r r r r� k s z'GoogleDocstring._escape_args_and_kwargs)�descr c C sx | � |�rdg| }n^|d �d�rt|dd � }| �|d �}| �|�}||kr\dg| }nd|d g| �|d� }|S )Nr r �::rp � )�_is_listr� r� �_get_initial_indent�_indent)rh r� Z
desc_blockrq Z block_indentr r r �_fix_field_descv s
z GoogleDocstring._fix_field_desc)�
admonitionri r c C sj | � |�}t|�dkr.d||d �� f dgS |rZ| �| �|�d�}d| dg| dg S d| dgS d S )Nrp z
.. %s:: %sr r � z.. %s::)� _strip_empty�lenr� r� r� )rh r� ri r r r �_format_admonition� s
z"GoogleDocstring._format_admonition)�prefixri �paddingr c C sv |rl|d u rdt |� }g }t|�D ]B\}}|dkrH|�|| �� � q$|r\|�|| � q$|�d� q$|S |gS d S )N� r r )r� � enumerateru r- )rh r� ri r� Z result_lines�irw r r r �
_format_block� s z GoogleDocstring._format_block�param�type)r� �
field_role� type_roler c C s� g }|D ]p\}}}| � |�}t|�rN| �|�}d||f }|�| �||�� n|�d||f � |r|�d|||f � q|dg S )Nz:%s %s: z:%s %s:z
:%s %s: %sr )r� �anyr� �extendr� ru ) rh r� r� r� ri rL r r� �fieldr r r �_format_docutils_params� s
z'GoogleDocstring._format_docutils_params)rL r r� r c C s� | � |�}t|�}|rdnd}|r\|rNd|v r>d|||f }qZd|||f }q�d||f }n,|r�d|v rvd||f }q�d||f }nd}|r�| �|�}|d r�||d g|d
d � S |g| S n|gS d S ) Nz -- r �`z
**%s** (%s)%sz**%s** (*%s*)%sz**%s**%sz%s%sz*%s*%sr rp )r� r� r� )rh rL r r� Zhas_desc� separatorr� r r r �
_format_field� s(
z GoogleDocstring._format_field)�
field_typer� r c
C s� d|� � }dt|� }t|�dk}g }|D ]f\}}}| �|||�} |r||rd|�| �|d | �� q�|�| �|d | �� q,|�| �|d | �� q,|r�|d r�|�d� |S )Nz:%s:r� rp z * r� r )r� r� r� r� r� ru )
rh r� r� r� �multiri rL r r� r� r r r �_format_fields� s
z GoogleDocstring._format_fieldsr )�
peek_aheadr c C sP | j �|d �| }|| j jkrL|r.| �|�S |d7 }| j �|d �| }qdS )Nrp r )rR rr �sentinelr� )rh r� rw r r r �_get_current_indent� s
z#GoogleDocstring._get_current_indent)rw r c C s* t |�D ]\}}|�� s| S qt|�S r, )r� �isspacer� )rh rw r� r. r r r r� � s
zGoogleDocstring._get_indent)ri r c C s |D ]}|r| � |� S qdS �Nr �r� r} r r r r� � s z#GoogleDocstring._get_initial_indentc C s> d }|D ],}|r| � |�}|d u r(|}q||k r|}q|p<dS r� r� )rh ri r� rw rq r r r r� � s
z GoogleDocstring._get_min_indentr� )ri �nr c s � fdd�|D �S )Nc s g | ]}d � | �qS )r� r r� �r� r r r� � r0 z+GoogleDocstring._indent.<locals>.<listcomp>r )rh ri r� r r� r r� � s zGoogleDocstring._indent)rw rq r c C s2 t |�D ]$\}}||kr dS |�� s dS qdS )NTF)r� r� )rh rw rq r� r. r r r rt s z GoogleDocstring._is_indentedc C s� |sdS t �|d �rdS t�|d �r,dS t|�dk sF|d �d�rJdS | �|d �}|}|dd � D ]}|rh| �|�} q�qh||kS )NFr Tr� r� rp )�_bullet_list_regexr� �_enumerated_list_regexr� r� r� )rh ri rq Z next_indentrw r r r r� s
zGoogleDocstring._is_listc C sz | j �� �� }t�|�}|rJ|�d�| jv rJ| �|�}| jdd�}||kS | j rvt
�|�rv| j D ]}|� |�r` dS q`dS )Nr� rp )r� TF) rR rr r� �_google_section_regexr� r� r3 r� r� r2 �_directive_regex�
startswith)rh r� r� Z
header_indentZsection_indent�directive_sectionr r r rz s
z"GoogleDocstring._is_section_headerc C s8 | j �� }| j �� p6| �� p6| jo6|o6| �|| j� S r, �rR rr ry rz rT rt rU )rh rw r r r rs ( s
���z!GoogleDocstring._is_section_breakc C s� | j jd ur�| j jD ]�}t|t�r4| j| j|�� < q|d dkrV| j| j|d �� < q|d dkrx| j| j|d �� < q| j� |d �� | j�| j|d �� < qd S )Nrp Z params_styler Z
returns_style)
rH Znapoleon_custom_sectionsrO rP � _parse_custom_generic_sectionr3 r� �"_parse_custom_params_style_section�#_parse_custom_returns_style_section�get)rh �entryr r r rf 0 s
� ���z%GoogleDocstring._load_custom_sectionsc C s� | � � | _| jrN| jdv rNg }z | �� }W n ty< Y n0 | j�|� d S | j�� r�| � � r�zT| �
� }d| _ | � � | _
t�|�r�|g| �� }n| j|�� |�}W d| _ d| _
q�d| _ d| _
0 n | js�| �� | � � }n| �� }| j�|� qNd S )N)Z attribute�data�propertyTFr )r~ rS rL rK �_parse_attribute_docstring�
StopIterationr� rR ry rz r� rT r� rU r� r� r� r3 r� r| )rh �resr� ri r r r rg F s4
�
zGoogleDocstring._parse)r� r� r c C s | � � }| �||�S r, )r� r� )rh r� r� ri r r r rX h s z!GoogleDocstring._parse_admonitionc C s4 | � � \}}| �dd|�}|r0|�dd| g� |S )Nr � :type: %s)r� r� r� )rh r r� ri r r r r� m s
z*GoogleDocstring._parse_attribute_docstring�r� r c C s g }| � � D ]�\}}}|s$| �|�}| jjrl| �|| j�}d| }|�| �||�� |r�|�d||f � q |�d| � | j r�d| j v r�|�d� |�d� | �
dd|�}|�| � |d�� |r�|�d� |�| � d| gd�� |�d� q | jj�r|�d� |S ) Nz
:ivar %s: z:vartype %s: %sz.. attribute:: �noindex� :noindex:r r� r� ) r� �_lookup_annotationrH Znapoleon_use_ivar�
_qualify_namerM r� r� ru rN r� r� )rh r� ri rL r r� r� r� r r r rY t s.
z)GoogleDocstring._parse_attributes_sectionc C s6 t d�t d�d�}| jj}|�|�� |�}| �||�S )NZExampleZExamples)r? r@ )r rH Z$napoleon_use_admonition_for_examplesr� r� �_parse_generic_section)rh r� �labels�use_admonitionZlabelr r r rZ � s �z'GoogleDocstring._parse_examples_sectionc C s | � |d�S )NF)r� �rh 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 dd�}| �||�S )NT�r� )r� r� �rh r� r� r r r r� � s z3GoogleDocstring._parse_custom_returns_style_sectionc C s6 ddg}ddg}| � � }| �|d�}|| | dg S )Nz.. rubric:: Usage:r z.. code-block:: pythonr� )r� r� )rh r� �header�blockri r r r �_parse_usage_section� s
z$GoogleDocstring._parse_usage_section)r� r� r c C s\ | � | �� �}| �|�}|r2d| }| �|d�}nd| }|rP|dg| dg S |dgS d S )Nz.. admonition:: %sr� z.. rubric:: %sr )r� r� r� r� )rh r� r� ri r� r r r r� � s
z&GoogleDocstring._parse_generic_sectionc C s4 | � � }| jjr | j|ddd�S | �td�|�S d S )N�keywordZkwtype)r� r� zKeyword Arguments)r� rH Znapoleon_use_keywordr� r� r r� r r r r[ � s �z0GoogleDocstring._parse_keyword_arguments_sectionc C sn g }| j dd�D ]X\}}}|�d| � | jrBd| jv rB|�d� |r^|�dg| �|d� � |�d� q|S )NF)r� z.. method:: %sr� r� r r� )r� ru rN r� r� )rh r� ri rL r r� r r r r\ � s
z&GoogleDocstring._parse_methods_sectionc C s | j j}| �td�|�S )NZNotes)rH Z!napoleon_use_admonition_for_notesr� r �rh r� r� r r r r] � s z$GoogleDocstring._parse_notes_sectionc C s: | j jr | jdd�}| �|�S | �� }| �td�|�S d S )NT�r� zOther Parameters�rH Znapoleon_use_paramr� r� r� r r� r r r r^ � s
z/GoogleDocstring._parse_other_parameters_sectionc C s: | j jr | jdd�}| �|�S | �� }| �td�|�S d S )NTr� Z
Parametersr� r� r r r rW � s
z)GoogleDocstring._parse_parameters_sectionc
C s� | j ddd�}g }|D ]�\}}}| j�|�}|rF|�d�rF|�d�}n$t�|�rj|�d�}||d d� }|rvd| nd }| �|�}t|�r�dd
�|� nd } |� d || f � q|r�|� d � |S ) NFT)r� r� r% r� rp r� r� r z
z :raises%s:%s)
r� � _name_rgxr� r� � _xref_regex�findr� r� rm ru )
rh r� r� ri rL r r� �m�posr� r r r ra � s
z%GoogleDocstring._parse_raises_sectionc C s: | j jr | jdd�}| �|�S | �� }| �td�|�S d S )NTr� ZReceivesr� r� r r r r_ � s
z'GoogleDocstring._parse_receives_sectionc C s | j j}| �td�|�S )NZ
References)rH Z&napoleon_use_admonition_for_referencesr� r r� r r r rb � s z)GoogleDocstring._parse_references_sectionc
C s� | � � }t|�dk}|r dn| jj}g }|D ]�\}}}|rJ| �|d|�} n| �|||�} |r�|rt|�| �d| �� q�|�| �d| �� q,t| �r�|�| �d| �� |r,|r,|�d| dg� q,|r�|d r�|�d� |S ) Nrp Fr z * z :returns: * z
:returns: z
:rtype: %sr� ) r� r� rH Znapoleon_use_rtyper� r� r� r� ru )
rh r� r� r� Z use_rtyperi rL r r� r� r r r r` s&
z&GoogleDocstring._parse_returns_sectionc C s | � d|�S �N�seealso)rX r� r r r rc s z'GoogleDocstring._parse_see_also_sectionc C s | � td�| �� �S )NZWarns)r� r r� r� r r r rd s z$GoogleDocstring._parse_warns_sectionc C s | j dd�}| �td�|�S )NTr� ZYields)r� r� r r� r r r re ! s z%GoogleDocstring._parse_yields_sectionc C s� g }g }d}d}t t�|��D ]�\}}|r6|�|� q t�|�}|d dkr�|r�d}||�� |�� � }|�|d |�� � � |�||�� d � � q |�|� q d�|�� � |d�|�� � fS )Nr Fr� r T)
r� �_xref_or_code_regexr� ru �_single_colon_regex�search�start�endrm r� ) rh rw Z before_colonZ after_colonr� Z found_colonr� �sourcer r r r r� % s$
�z)GoogleDocstring._partition_field_on_colon)� attr_name�klassr c C sV |rRd|vrR|� d�r"|dd � }z
|j}W n tyD |j}Y n0 d||f S |S )N�.�~rp z~%s.%s)r� � __qualname__�AttributeError�__name__)rh r r �qr r r r� ; s
z GoogleDocstring._qualify_namec C s� |r�d}t |�D ]\}}|r|} q&q|dkr2g }d}ttt|���D ]}|| }|rF|} q`qF|dksx|d t|�k r�|||d � }|S )Nr� r rp )r� �reversed�ranger� )rh ri r r� rw r r r r r� F s" z GoogleDocstring._strip_empty)rL r c C st | j jrp| jdv rp| jrpt| d�sXt| j di �}|�t| j di �pDi � t| jd |�| _|| jv rpt | j| �S dS )N)r) r( � exception� _annotationsZautodoc_type_aliasesr� r )
rH Znapoleon_attr_annotationsrK rM rV r� �updater r r )rh rL �localnsr r r r� Y s
��
z"GoogleDocstring._lookup_annotation)NNr r NN)rp )TF)TFF)F)F)N)r� r� )r )r� )rp )Lr �
__module__r �__doc__�re�compile�Xr� r rP r � SphinxConfigr
r rj ro ri �intrx r| r~ �boolr r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� rt r� rz rs rf rg rX r� rY rZ r� r� r� r� r� r[ r\ r] r^ rW ra r_ rb r` rc rd re r� r r� r� r� r r r r r F s� >� �� L � ��
�
�� � "
r )�tokensr c s2 t �| �}d� � fdd���fdd�}t||��S )N�Zoptional�defaultc 3 s� d}d }z | � � }W n ty* Y q�Y n0 |dkr:|}q|�� sDq|� v rj| �|� |d ur�| �|� q�|d ur||V d }|dkr�|d7 }n|dkr�|d8 }|V |dkrq�qd S )Nr �, �{rp �})�popleft�
IndexErrorr� �
appendleft)r! Z open_bracesZprevious_token�token)�keywordsr r �
takewhile_setm s4
z,_recombine_set_tokens.<locals>.takewhile_setc 3 sT z | � � }W n ty" Y qPY n0 |dkrH| �d� d�� | ��V q |V q d S )Nr% r )r' r( r) rm )r! r* )r, r r � combine_set� s
z*_recombine_set_tokens.<locals>.combine_set)� collections�deque�list)r! Z token_queuer- r )r+ r, r �_recombine_set_tokensi s
$
r1 )�specr c s( dd� � t � fdd�t�| �D ��}|S )Nc S s6 t �| �r,| d d� }| dd � }|d|gS | gS d S )N� � r� )�_default_regexr� )�itemr# �otherr r r � postprocess� s
z(_tokenize_type_spec.<locals>.postprocessc 3 s$ | ] }� |�D ]}|r|V qqd S r, r )r� Z raw_tokenr6 �r8 r r � <genexpr>� s �z&_tokenize_type_spec.<locals>.<genexpr>)r0 � _token_regexr� )r2 r! r r9 r �_tokenize_type_spec� s
�r< )r* �locationr c C s> dd� }| � d�s | �d�r$d}�n|| �sh| � d�r@| �d�sh| � d�rT| �d�sh| � d�rn| �d�rnd }n�| � d�r�tjtd
�| |d � d }n�| �d�r�tjtd �| |d � d }n�| � d�s�| � d�r�tjtd
�| |d � d }nV| �d�s�| �d��rtjtd�| |d � d }n&| dv �r$d}nt�| ��r6d}nd}|S )Nc S s* z t | � W n ty Y dS 0 dS 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): %sz4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %sr" �control� referencer& )r� r� �loggerr= r r� r� )r* r= r@ �type_r r r � _token_type� sh �������
�
���
rJ )r r= r r c sp dd� � t | �}t|�}�fdd�|D �}dd� � �fdd�dd� d d� d
d� d ��d ��fd
d�|D ��}|S )Nc S sP |� | | �}|tv r"|dkr"d}n|dkr6|dkr6d}t�|�d u rL|| }|S )Nr � :obj:`%s`z...z:obj:`%s <Ellipsis>`)r� � _SINGLETONSr� r� )r& r Zdefault_translation� translationr r r � convert_obj� s z-_convert_numpy_type_spec.<locals>.convert_objc s g | ]}|t |� �f�qS r )rJ )r� r* rE r r r� s �z,_convert_numpy_type_spec.<locals>.<listcomp>c S s d| S )Nz``%s``r ��xr r r r/ r0 z*_convert_numpy_type_spec.<locals>.<lambda>c s � | �d�S )Nr r rO )rN r r r r/
r0 c S s d| S )Nz*%s*r rO r r r r/ r0 c S s | S r, r rO r r r r/ r0 c S s | S r, r rO r r r r/
r0 )rD r& rF rA rG r c 3 s | ]\}}� � |�|�V qd S r, )r� )r� r* rI )�
convertersr r r: r0 z+_convert_numpy_type_spec.<locals>.<genexpr>)r< r1 rm )r r= r r! Zcombined_tokens�typesZ convertedr )rN rQ r= r r �_convert_numpy_type_spec� s
� �rS c
s e Zd ZdZd!eeee f eeeee e dd�� fdd�
Z
ed�dd �Z eed
�� fd d � Z d"e
e
eeeee f d�dd�Zd#e
eeeeee f d�dd�Zed�dd�Ze
d�dd�Ze
d�dd�Zeee d�d d �Zee ee d �d d �Z� ZS )$�NumpyDocstringa�
Convert NumPy style docstrings to reStructuredText.
Parameters
----------
docstring : :obj:`str` or :obj:`list` of :obj:`str`
The docstring to parse, given either as a string or split into
individual lines.
config: :obj:`sphinx.ext.napoleon.Config` or :obj:`sphinx.config.Config`
The configuration settings to use. If not given, defaults to the
config object on `app`; or if `app` is not given defaults to the
a new :class:`sphinx.ext.napoleon.Config` object.
Other Parameters
----------------
app : :class:`sphinx.application.Sphinx`, optional
Application object representing the Sphinx process.
what : :obj:`str`, optional
A string specifying the type of the object to which the docstring
belongs. Valid values: "module", "class", "exception", "function",
"method", "attribute".
name : :obj:`str`, optional
The fully qualified name of the object.
obj : module, class, exception, function, method, or attribute
The object to which the docstring belongs.
options : :class:`sphinx.ext.autodoc.Options`, optional
The options given to the directive: an object with attributes
inherited_members, undoc_members, show_inheritance and noindex that
are True if the flag option of same name was given to the auto
directive.
Example
-------
>>> from sphinx.ext.napoleon import Config
>>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True)
>>> docstring = '''One line summary.
...
... Extended description.
...
... Parameters
... ----------
... arg1 : int
... Description of `arg1`
... arg2 : str
... Description of `arg2`
... Returns
... -------
... str
... Description of return value.
... '''
>>> print(NumpyDocstring(docstring, config))
One line summary.
<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 r c s$ dg| _ t� �|||||||� d S )Nz
.. index::)r2 �superrj )rh r! r" r# r$ r% r& r' �r� r r rj r s zNumpyDocstring.__init__rk c C sn z | j d urt�| j �nd }W n ty4 d }Y n0 | j}|d u rP|d u rPd S |d u r\d}d�|d| g�S )Nr r� zdocstring of %s)rM rI Zgetfile� TypeErrorrL rm )rh �filepathr% r r r �
_get_locationx s
z NumpyDocstring._get_locationr� c s: t � j� d|v r.d�� fdd�|�d�D ��S � |�S d S )Nr$ c 3 s | ]}� |�V qd S r, r )r� r� ��funcr r r: � r0 z9NumpyDocstring._escape_args_and_kwargs.<locals>.<genexpr>)rU r� rm r� r� rV rZ r r� � s z&NumpyDocstring._escape_args_and_kwargsTFr c C s� t | j�}|r | �|�\}}}n
|d }}|�� |�� }}| �|�}|rX|sX| �|�}|rj|sj|| }}| jjr�t|| � � | jj
p�i d�}| � |�d }| � | �
|��}| �|| j��� }|||fS )Nr )r= r rp )rv rR r� r� r� r� rH r� rS rY r� r� r� rx r� ri ) rh r� r� rw rL r r rq r� r r r r� � s(
�z NumpyDocstring._consume_fieldr� c C s | j dd�S )NT)r� )r� )rh r� r r r r� � s z'NumpyDocstring._consume_returns_sectionc C s" t | j�}t�|�s t | j� |S r, )rv rR r� r� r� r r r r� � s
z&NumpyDocstring._consume_section_headerc C sN | j �d�\}}| j �� pL| �� pLddg||gkpL| joL|oL| �|| j� S )Nr� r r� )rh Zline1Zline2r r r rs � s ����z NumpyDocstring._is_section_breakc C sj | j �d�\}}|�� }|| jv r:t|t�r:tt�|��S | j rft
�|�rf| j D ]}|� |�rP dS qPdS )Nr� TF) rR rr r� r3 rO rP r �_numpy_section_regexr� r2 r� r� )rh r� Z underliner� r r r rz � s
z!NumpyDocstring._is_section_headerr� c C s8 | � � }z | �|�W S ty2 | �d|� Y S 0 d S r )r� � _parse_numpydoc_see_also_sectionr? r� )rh r� ri r r r rc � s
z&NumpyDocstring._parse_see_also_section)�contentr c s g � t tt t f d��fdd� �t tt dd�� �fdd� }�fdd ��d}g }|D ]�}|�� sbqT�j�|�}|r�||�� d� �� �d
�r�|||� |d|�� � ||�� d� }}|�d
d �d �� g}|d s�g }qT|�d
��s8|||� d}d|v �r(|�d�D ]}|�� �r
||g � �q
n|�� �rN|}qT|durT|� |�� � qT|||� � �sdg S �fdd�� D �� g }d} � D ]�\}
} } | �r�d| |
f }
nd|
}
| �s�| �r�|dg7 }||
g7 }n|d d|
7 < | �r |��
d
� | �g�7 }d} nd} �q�|dg7 }�� d|�S )a
Derived from the NumpyDoc implementation of _parse_see_also.
See Also
--------
func_name : Descriptive text
continued text
another_func_name : Descriptive text
func_name1, func_name2, :meth:`func_name`, func_name3
)�textr c sP � j �| �}|r@|�� }|d du r0|d dfS |d |d fS td| ��dS )z Match ':role:`name`' or 'name'rp Nr� r� z%s is not a item name)r� r� �groupsr? )r_ r �grn r r �parse_item_name� s zHNumpyDocstring._parse_numpydoc_see_also_section.<locals>.parse_item_nameN)r% �restr c s6 | sd S �| �\} }� � | t|�|f� |d d �= d S r, )ru r0 )r% rc �role)�itemsrb r r � push_item� s
zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.push_itemc sn � j j}|d us|s | ||fS |�| | �}� j�|�}|sD|||fS |�� }|d }|d pb|d }|||fS )Nrd r% Zname2)rH r� r� r� r� � groupdict)r[ � descriptionrd r Z
translatedr� r` �new_funcrn r r � translate� s
zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.translater� rp r r� r� c s g | ]\}}}� |||��qS r r )r� r[ rh rd )rj r r r� s �zCNumpyDocstring._parse_numpydoc_see_also_section.<locals>.<listcomp>Tz:%s:`%s`rK r r� z, %sFr )
rP r r r� r� r� r r� r� ru r� rm r� )rh r^ rf Z current_funcrc rw r r[ ri Z
last_had_descr% r� rd �linkr )re rb rh rj r r] � sb
"
�
z/NumpyDocstring._parse_numpydoc_see_also_section)NNr r NN)TF)F)r r r r r rP r r r
r rj rY r� r r r� r� r� rs rz rc r] �
__classcell__r r rV r rT s* \ ��� � rT )N)7r r. rI r � functoolsr �typingr r r r r r r Zsphinx.applicationr
Z
sphinx.configr r Z sphinx.ext.napoleon.iteratorsr
Z
sphinx.localer r Z sphinx.utilr Zsphinx.util.inspectr Zsphinx.util.typingr Z getLoggerr rH r r� r� r� r\ r r r� r� r� r; r5 rL rP r r r1 r< rJ �dictrS rT r r r r �<module> s` $
��
���
)8;$