HEX

File: //usr/lib/python3/dist-packages/sphinx/ext/autosummary/__pycache__/generate.cpython-310.pyc
o

o�a�`�@s8dZddlZddlZddlZddlZddlZddlZddlZddlZddl	Z	ddl
mZddlmZddl
mZmZmZmZmZmZmZmZddlmZddlmZddlZddlmZmZdd	lmZdd
l m!Z!ddl"m#Z#ddl$m%Z%dd
l&m'Z'ddl(m)Z)ddl*m+Z+m,Z,m-Z-ddlm.Z.ddl/m0Z0m1Z1ddl2m3Z3ddl4m5Z5m6Z6m7Z7ddl8m9Z9ddl:m;Z;ddl<m=Z=e5�>e?�Z@Gdd�d�ZAGdd�de�ZBdeddfdd�ZCdeDddfd d!�ZEdeDddfd"d#�ZFdXd%eDd&eDdeDfd'd(�ZGGd)d*�d*�ZHGd+d,�d,�ZI	dYd-eDd.ed/ed0eHd1eDd2eJded3eJd4ed5eDd6eDdeDfd7d8�ZK					<dZd=eeDd>eDd?eDd@eDdAe!dBeDd2eJdedCeJdDeDddfdEdF�ZLdGeeDdeeBfdHdI�ZMdYd-eDdJeDdKeDdeeBfdLdM�ZNdYdNeeDdJeDdKeDdeeBfdOdP�ZOdejPfdQdR�ZQejRdSd�fdTeeDddfdUdV�ZSe?dWk�r�eS�dSdS)[a"
    sphinx.ext.autosummary.generate
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Usable as a library or script to generate automatic RST source files for
    items referred to in autosummary:: directives.

    Each generated RST file contains a single auto*:: directive which
    extracts the docstring of the referred item.

    Example Makefile rule::

       generate:
               sphinx-autogen -o source/generated source/*.rst

    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
�N)�NullTranslations)�path)�Any�Dict�List�
NamedTuple�Set�Tuple�Type�Union)�TemplateNotFound)�SandboxedEnvironment)�__display_version__�package_dir)�Sphinx)�Builder)�Config)�RemovedInSphinx50Warning)�
Documenter)�
import_module)�get_documenter�import_by_name�import_ivar_by_name)�__)�ModuleAnalyzer�PycodeError)�SphinxComponentRegistry)�logging�rst�split_full_qualified_name)�safe_getattr)�	ensuredir)�SphinxTemplateLoaderc@s4eZdZdZdeddfdd�Zdeddfdd	�ZdS)
�DummyApplicationz3Dummy Application class for sphinx-autogen command.�
translator�returnNcCsft�|_t�|_g|_d|_||_d|_d|_d|_	|j�
didd�|j�
didd�|j��dS)N�/rF�autosummary_contextT�autosummary_filename_map)r�configr�registry�
messagelog�srcdirr$�	verbosity�
_warncount�warningiserror�add�init_values)�selfr$�r3�A/usr/lib/python3/dist-packages/sphinx/ext/autosummary/generate.py�__init__;szDummyApplication.__init__�argscGsdS�Nr3)r2r6r3r3r4�emit_firstresultIsz!DummyApplication.emit_firstresult)�__name__�
__module__�__qualname__�__doc__rr5rr8r3r3r3r4r#8sr#c@s.eZdZUeed<eed<eed<eed<dS)�AutosummaryEntry�namer�template�	recursiveN)r9r:r;�str�__annotations__�boolr3r3r3r4r=Ms

r=�appr%cCslddlm}m}m}m}m}m}m}m}m	}	m
}
m}|||||||	|
|||g}|D]
}
|j�
|
j|
�q)dS)Nr)�AttributeDocumenter�ClassDocumenter�DataDocumenter�DecoratorDocumenter�ExceptionDocumenter�FunctionDocumenter�MethodDocumenter�ModuleDocumenter�NewTypeAttributeDocumenter�NewTypeDataDocumenter�PropertyDocumenter)�sphinx.ext.autodocrErFrGrHrIrJrKrLrMrNrOr*�add_documenter�objtype)rDrErFrGrHrIrJrKrLrMrNrO�documenters�
documenterr3r3r4�setup_documentersTs4��rU�msgcCstjdtdd�t|�dS)Nz_simple_info() is deprecated.���
stacklevel)�warnings�warnr�print�rVr3r3r4�_simple_infocs�r^cCs&tjdtdd�td|tjd�dS)Nz_simple_warn() is deprecated.rWrXz	WARNING: )�file)rZr[rr\�sys�stderrr]r3r3r4�_simple_warnis�rb�=�title�linecCs$d|vrtd��|d|t|�S)N�
zCan only underline single lines)�
ValueError�len)rdrer3r3r4�
_underlineosric@sXeZdZdZddeeefdeddfdd�Zdede	fd	d
�Z
dededefdd
�ZdS)�AutosummaryRendererzA helper class for rendering.NrD�template_dirr%cCs�t|t�r
tjdtdd�|rtjdtdd�tj�tddd�g}t	|j
|jj|�}t
|d�|_tj|jjd	<tj|jjd
<t|jjd<t|ttf�r_|jr]|j�d�|j�|j�dSdSt|t�rx|jjrz|j�d�|j�|jj�dSdSdS)
NzLThe first argument for AutosummaryRenderer has been changed to Sphinx objectrWrXz<template_dir argument for AutosummaryRenderer is deprecated.�ext�autosummary�	templates)�loader�escape�e�	underlinezjinja2.ext.i18n)�
isinstancerrZr[r�osr�joinrr"r,r)�templates_pathr
�envrrp�filtersrirr#r$�
add_extension�install_gettext_translationsrD)r2rDrk�system_templates_pathror3r3r4r5xs6
����
�zAutosummaryRenderer.__init__�
template_namecCs8tjdtdd�z	|j�|�WdStyYdSw)zCheck if template file exists.z+AutosummaryRenderer.exists() is deprecated.rWrXTF)rZr[rrw�get_templater)r2r|r3r3r4�exists�s��zAutosummaryRenderer.exists�contextcCsbz|j�|�}Wn#ty+z
|j�d|�}Wnty(|j�d�}YnwYnw|�|�S)zRender a template file.zautosummary/%s.rstzautosummary/base.rst)rwr}r�render)r2r|rr?r3r3r4r��s���
zAutosummaryRenderer.renderr7)
r9r:r;r<rrrrAr5rCr~rr�r3r3r3r4rjus
 
rjc@sheZdZdededdfdd�Zdededefd	d
�Zdedededefdd
�Zdede	efdd�Z
dS)�
ModuleScannerrD�objr%NcCs||_||_dSr7)rD�object)r2rDr�r3r3r4r5�s
zModuleScanner.__init__r>�valuecCst|j||j�jSr7)rrDr�rR)r2r>r�r3r3r4�get_object_type�szModuleScanner.get_object_typerRc
CsVz|j�d|||di�WSty*}ztjtd�||dd�WYd}~dSd}~ww�Nzautodoc-skip-memberFz\autosummary: failed to determine %r to be documented, the following exception was raised:
%srm)�type)rDr8�	Exception�logger�warningr)r2r>r�rR�excr3r3r4�
is_skipped�s
�
���zModuleScanner.is_skipped�imported_membersc	Cs�g}t|j�D]Y}zt|j|�}Wntyd}Ynw|�||�}|�|||�r+qzt�|�r4d}nt|d�|jjkr@d}nd}WntyNd}Ynw|rW|�	|�q|dur`|�	|�q|S)NTr:F)
�dirr�r �AttributeErrorr�r��inspect�ismoduler9�append)r2r��membersr>r�rR�importedr3r3r4�scan�s4�
��
�zModuleScanner.scan)r9r:r;rr5rAr�rCr�rr�r3r3r3r4r��s

r�r>r��parentr?r|r�r@r�modname�qualnamecst�||��dtdtdtdtf�fdd��dtdtttff�fdd��dtdtttffd	d
��dtdtttff���fdd��gd
fdtdttdttdtdtttttff
���fdd�
}dtdtttttff�fdd�}dtdtttttff�fdd�}
i}|�|��j	dkr�t
�|�}|�|�|d<||dh|d�\|d<|d<||dh|d�\|d<|d<||d h|d�\|d!<|d"<||d�\|d#<|d$<t|d%�}|r�|r�|
|�\|d&<|d'<n6�j	dk�r"t
|�|d<tt
|��t|j���|d(<||d)hd*g�\|d+<|d,<||d-d.h�\|d#<|d$<|	du�s,�du�r2t��\}	��j	d/v�rB��d0d1�d2|d<�j	d3v�rK�}n��d0d1�d4}�|d5<|	|d<�|d6<||d<�j	|d<t��d7|d8<|�ry|�||�S|��j	|�S)9Nr�r>rRr%c
sTz��d|||di�WSty)}ztjtd�||dd�WYd}~dSd}~wwr�)r8r�r�r�r)r�r>rRr�)rDr3r4�skip_member�s
�
���z1generate_autosummary_content.<locals>.skip_membercs&tjj�|�gt�}dd�|��D�S)NcSsi|]\}}||j�qSr3)r�)�.0r>�memberr3r3r4�
<dictcomp>�szKgenerate_autosummary_content.<locals>.get_class_members.<locals>.<dictcomp>)�sphinxrl�autodoc�get_class_membersr �items)r�r�)r�r3r4r��sz7generate_autosummary_content.<locals>.get_class_membersc	Ss:i}t|�D]}z	t||�||<WqtyYqw|Sr7)r�r r�)r�r�r>r3r3r4�get_module_members�s�z8generate_autosummary_content.<locals>.get_module_memberscs(�jdkr	�|�S�jdkr�|�SiS)N�module�class)rR)r�)�docr�r�r3r4�get_all_members�s


z5generate_autosummary_content.<locals>.get_all_membersT�types�include_publicr�cs�g}g}�|�}|��D]H\}}t�||�}	|	j|vrT|s&t|dd�|jkrT�|||	j�}
|
dur2q|
durA|�|�|�|�q|�|�||vsO|�d�sT|�|�q||fS)Nr:TF�_)r�rrR�getattrr9r��
startswith)r�r�r�r�r��public�all_membersr>r�rT�skipped)rDr�r�r3r4�get_memberss$



�z1generate_autosummary_content.<locals>.get_membersr�cs|gg}}z,t���}|��}|D]\}}|dkr,||vr,|�|�|�d�s,|�|�qW||fSty=Y||fSw)z'Find module attributes with docstrings.�r�)r�
for_module�find_attr_docsr�r�r)r��attrsr��analyzer�	attr_docs�	namespace�	attr_name�r>r3r4�get_module_attrss 




����z6generate_autosummary_content.<locals>.get_module_attrsc	szg}t�|j�D])\}}}�d|}zt|�}|r!t|d�r!WqWn	ty+Ynw|�|�qdd�|D�}||fS)N�.�__sphinx_mock__cSs$g|]}|�d�d�d�s|�qS)r����r�)�splitr�)r��xr3r3r4�
<listcomp>:s$zEgenerate_autosummary_content.<locals>.get_modules.<locals>.<listcomp>)�pkgutil�iter_modules�__path__r�hasattr�ImportErrorr�)r�r�r�r��ispkg�fullnamer�r�r�r3r4�get_modules.s��z1generate_autosummary_content.<locals>.get_modulesr��function)r��	functions�
all_functionsr��classes�all_classes�	exception�
exceptions�all_exceptions�
attributes�all_attributesr��modules�all_modules�inherited_members�methodr5�methods�all_methods�	attribute�property)r�r�r�r��r)r�r�r��objnamercrr)rrrArCrrrr	�updaterRr�r�r�r��set�__dict__�keysr�rsplitrhr�)r>r�r�r?r|r�rDr@rr�r�r�r�r��ns�scanner�	ispackage�	shortnamer3)rDr�r�r�r�r>r�r�r4�generate_autosummary_content�sn
"	���&&


���
�
����
r��.rstFT�utf-8�sources�
output_dir�suffix�	base_path�builderrk�	overwrite�encodingc

s
|r
tjdtdd�|rtjdtdd�tt|��}
t|
�dkr/|
dd�dg|
dd�}
t�td	�d
�	|
��|rFt�td�|��durS�fdd
�|D�}t
|�}t|�}g}
|rd|jj
}ni}tt|�td�D�]}|jdurwqn|ptj�|j�}t|�zt|j�\}}}}|�|dd�}Wn@ty�}z4zt|j�\}}}}|�|dd�}Wnty�t�td�|j|f�YWYd}~qnwWYd}~nd}~wwi}|r�|�|jj�t|||||j|||j|||�}tj�	||�||�|�}tj� |��rNt!||	d��}|�"�}Wd�n	1�swY||k�r(qn|�rMt!|d|	d��
}|�#|�Wd�n	1�sCwY|
�$|�qnt!|d|	d��
}|�#|�Wd�n	1�sfwY|
�$|�qn|
�r�t%|
||�|||||d�	dSdS)Nz?builder argument for generate_autosummary_docs() is deprecated.rWrXzDtemplate_dir argument for generate_autosummary_docs() is deprecated.��
z...i����z,[autosummary] generating autosummary for: %sz, z[autosummary] writing to %scsg|]	}tj��|��qSr3)rtrru)r��filename�r�r3r4r��sz-generate_autosummary_docs.<locals>.<listcomp>)�keyr�r�z%[autosummary] failed to import %r: %s)r��w)r�r�r�r�rkr�rDr�)&rZr[r�list�sortedrhr��inforrurj�find_autosummary_in_filesr)r(r�rArrt�abspathr!rr>�replacer�rr�r�r'r�r?r@�get�isfile�open�read�writer��generate_autosummary_docs)r�r�r�r�r�rkr�rDr�r��showed_sourcesr?r��	new_files�filename_map�entryrr>r�r�r�r�rqr�contentr��f�old_contentr3r�r4r�ps���
�

����	
�
�
�
��
��r��	filenamesc	Cs^g}|D](}t|ddd��}|����}|�t||d��Wd�n1s'wYq|S)z^Find out what items are documented in source/*.rst.

    See `find_autosummary_in_lines`.
    r��ignore)r��errors�r�N)r�r��
splitlines�extend�find_autosummary_in_lines)r�
documentedr�r�linesr3r3r4r��s��r�r�r�c	
Cs�|r
tjdtdd�zt|�\}}}}t�|���}t|||d�WSty+YgSt	yE}zt
d||f�WYd}~gSd}~wtyTt
d|�YgSw)znFind out what items are documented in the given object's docstring.

    See `find_autosummary_in_lines`.
    zBmodule argument for find_autosummary_in_docstring() is deprecated.rWrX)r�r�zFailed to import '%s': %sNz_Failed to import '%s'; the module executes module level statement and it might call sys.exit().)rZr[rr�pydoc�getdocrr
r�r�r\�
SystemExit)	r>r�r��	real_namer�r�r�rrqr3r3r4�find_autosummary_in_docstring�s*������rrcCs�t�d�}t�d�}t�d�}t�d�}t�d�}t�d�}t�d�}	g}
d}d	}d	}
|}d}d
}|D]�}|r�|�|�}|rAd}q3|�|�}|r[|�d�}|rZtj�tj�|�|�}q3|	�|�}|rj|�d���}
q3|���	d
�rrq3|�|�}|r�|�d���}|�	d�r�|dd	�}|r�|�	|d�s�d||f}|
�
t|||
|��q3|��r�|�	|d�r�q3d}|�|�}|r�d}|�d�}d}d	}d	}
q3|�|�}|r�|�d���}|
�
t||d��q3|�|�}|r�|�d�}q3q3|
S)a�Find out what items appear in autosummary:: directives in the
    given lines.

    Returns a list of (name, toctree, template) where *name* is a name
    of an object and *toctree* the :toctree: path of the corresponding
    autosummary directive (relative to the root of the file name), and
    *template* the value of the :template: option. *toctree* and
    *template* ``None`` if the directive does not have the
    corresponding options set.
    z^(\s*)\.\.\s+autosummary::\s*z.^\s*\.\.\s+automodule::\s*([A-Za-z0-9_.]+)\s*$z4^\s*\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$z%^\s+(~?[_a-zA-Z][a-zA-Z0-9_.]*)\s*.*?z^\s+:recursive:\s*$z^\s+:toctree:\s*(.*?)\s*$z^\s+:template:\s*(.*?)\s*$FNr�Tr��:�~r�z%s.%s� r
rW)�re�compile�match�grouprtrru�dirname�stripr�r�r=�searchrr)rr�r��autosummary_re�
automodule_re�	module_re�autosummary_item_re�recursive_arg_re�toctree_arg_re�template_arg_rerr@�toctreer?�current_module�in_autosummary�base_indentre�mr>r3r3r4r
�s�
��






�


�


�

�r
cCs�tjdtd�td�d�}|jddddtd	�|jd
dtd�d
�|jddddtd�d�|jdddddtd�d�|jdddddtd�d�|jddd d!d"td#�d�|S)$Nz#%(prog)s [OPTIONS] <SOURCE_FILE>...z:For more information, visit <https://www.sphinx-doc.org/>.a�
Generate ReStructuredText using autosummary directives.

sphinx-autogen is a frontend to sphinx.ext.autosummary.generate. It generates
the reStructuredText files from the autosummary directives contained in the
given input files.

The format of the autosummary directive is documented in the
``sphinx.ext.autosummary`` Python module and can be read using::

  pydoc sphinx.ext.autosummary
)�usage�epilog�descriptionz	--version�version�show_versionz%%(prog)s %s)�action�destr.�source_file�+z&source files to generate rST files for)�nargs�helpz-oz--output-dir�storer�z directory to place all output in)r0r1r5z-sz--suffixr�rz/default suffix for files (default: %(default)s))r0r1�defaultr5z-tz--templatesrnz0custom template directory (default: %(default)s)z-iz--imported-members�
store_truer�Fz0document imported members (default: %(default)s))�argparse�ArgumentParserr�add_argumentr)�parserr3r3r4�
get_parserSs8�
��
���
�r=r��argvcCs�tj�tjd�tj�tj�td�d�tj�	gd�\}}t
|�}t�|t
jt
j�t|�t��|�}|jrB|jj�t�|j��t|j|jd|j|j|d�dS)Nr��localer�r�)r�rD)r�r?�	setlocale�LC_ALL�init_consolertrrur�initr#r�setupr`�stdoutrarUr=�
parse_argsrnr)rvr�r�r�r2r�r�r�)r>r$r�rDr6r3r3r4�main}s

�rG�__main__)rc)NN)	Nr�NNNFNTr�)Tr<r9r�r?rtr�rrr`rZ�gettextrr�typingrrrrrr	r
r�jinja2r�jinja2.sandboxr
�
sphinx.localer�rr�sphinx.applicationr�sphinx.buildersr�
sphinx.configr�sphinx.deprecationrrPr�sphinx.ext.autodoc.importerr�sphinx.ext.autosummaryrrrr�
sphinx.pycoderr�sphinx.registryr�sphinx.utilrrr�sphinx.util.inspectr �sphinx.util.osutilr!�sphinx.util.templater"�	getLoggerr9r�r#r=rUrAr^rbrirjr�rCr�r�r�rr
r:r=r>rGr3r3r3r4�<module>s�(
:6���������
����������
�_

�
�_$*

�