U
    \ShPy                     @  s  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ZddlmZ ddlm	Z	 ddl
mZ ddlmZmZmZmZ ddlmZ dd	lmZmZ dd
lmZ ddlmZmZmZ ddlmZ ddlZddlmZ ddl m!Z! ddl"m#Z# ddl$m%Z% ddl&m'Z'm(Z( ddl)m*Z*m+Z+ ddl,m-Z- ddl.m/Z/ ddl0m1Z1 ddl2m3Z3 ddl4m5Z5 ddl6m7Z7m8Z8 ddl9m:Z: ddl;m<Z<m=Z= ddl>m?Z?m@Z@mAZAmBZBmCZC ddlDmEZEmFZF ddlGmHZH ddlImJZJ ddlKmLZL e<MeNZOePd ZQePd!ZRd"ZSG d#d$ d$ejTZUd%d$d&d'd(d)ZVd%d*d&d'd+d,ZWG d-d. d.ejTZXd/d.d&d'd0d1ZYG d2d3 d3ZZG d4d5 d5e*Z[d6d7d7d8d9d:d;Z\G d<d= d=e@Z]d>d>d?d@dAZ^d>d>d?dBdCZ_dpd>dEd>dFdGdHZ`dId7d>dJdKdLZadqd>dIdEd>d>dNdOdPZbG dQdR dRecZddSdTdUdVdWZedgfd>dTdXdYdZd[Zfdrd>d]d^d_d`daZgdgd\fd>dTd]dXdbdcddZhG dedf dfeAZid6dgdhdidjZjd6d&dhdkdlZkd6dmdhdndoZldS )sa_  Extension that adds an autosummary:: directive.

The directive can be used to generate function/method/attribute/etc. summary
lists, similar to those output eg. by Epydoc and other API doc generation tools.

An :autolink: role is also provided.

autosummary directive
---------------------

The autosummary directive has the form::

    .. autosummary::
       :nosignatures:
       :toctree: generated/

       module.function_1
       module.function_2
       ...

and it generates an output table (containing signatures, optionally)

    ========================  =============================================
    module.function_1(args)   Summary line from the docstring of function_1
    module.function_2(args)   Summary line from the docstring
    ...
    ========================  =============================================

If the :toctree: option is specified, files matching the function names
are inserted to the toctree with the given prefix:

    generated/module.function_1
    generated/module.function_2
    ...

Note: The file names contain the module:: or currentmodule:: prefixes.

.. seealso:: autosummary_generate.py


autolink role
-------------

The autolink role functions as ``:obj:`` when the name referred can be
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
    )annotationsN)	Parameter)path)
ModuleType)AnyListSequencecast)nodes)Nodesystem_message)
directives)RSTStateMachineStructstate_classes)
StringList)addnodes)Sphinx)Config)BuildEnvironment)INSTANCEATTR
Documenter)DocumenterBridgeOptions)import_module)mock)	Extension)__)Project)ModuleAnalyzerPycodeError)SphinxComponentRegistry)loggingrst)NullReporterSphinxDirective
SphinxRolenew_documentswitch_source_input)getmrosignature_from_str)Matcher)
OptionSpec)HTML5Translatorz	\.(?:\s+)z::\s*$)zet al.z i.e.c                   @  s   e Zd ZdS )autosummary_tocN__name__
__module____qualname__ r3   r3   R/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/ext/autosummary/__init__.pyr.   i   s   r.   znodes.NodeVisitorNone)selfnodereturnc                 C  s
   t jdS )z-Hide autosummary toctree list in HTML output.N)r
   ZSkipNoder6   r7   r3   r3   r4   autosummary_toc_visit_htmlm   s    r:   r   c                 C  s   d S Nr3   r9   r3   r3   r4   autosummary_noopr   s    r<   c                   @  s   e Zd ZdS )autosummary_tableNr/   r3   r3   r3   r4   r=   x   s   r=   r-   c                 C  s   zt tj|d }t tj|d }t tj|d }t ttj |}|D ]d}t tj|d }t tj|d }t	t
|D ]2\}	}
t|
tjrv|
 dd}t|||	< qvqFW n tk
r   Y nX dS )z0Make the first column of the table non-breaking.r        N)r	   r
   tabletgrouptbodyr   rowentry	paragraph	enumeratelist
isinstanceTextastextreplace
IndexError)r6   r7   rA   rB   rC   rowsrD   Z
col1_entryZparjZsubnodenew_textr3   r3   r4   autosummary_table_visit_html|   s    rQ   c                   @  s   e Zd ZddddZdS )FakeApplicationr5   r8   c                 C  s8   d | _ d | _i | _d | _t | _td d | _t | _	d S r;   )
Z
doctreedirevents
extensionssrcdirr   configr   projectr!   registry)r6   r3   r3   r4   __init__   s    zFakeApplication.__init__N)r0   r1   r2   rZ   r3   r3   r3   r4   rR      s   rR   c                      s"   e Zd Zdd fddZ  ZS )FakeDirectiver5   rS   c                   sX   t dd}t |d}t }|jdddd  t|}t |d}t |d t d| d S )	N   )Z	tab_width)settingsZautodoc_class_signaturemixedT)documentr   )r   rR   rW   addr   superrZ   r   )r6   r]   r_   appenvstate	__class__r3   r4   rZ      s    


zFakeDirective.__init__)r0   r1   r2   rZ   __classcell__r3   r3   re   r4   r[      s   r[   r   r   ztype[Documenter])rb   objparentr8   c                   s   ddl m}m} t r|S |dk	r4t| |d}n|}t|drR|t |jn|t d fdd| j	j
 D }|r|jdd	 d
 |d S |S dS )zGet an autodoc.Documenter class suitable for documenting the given
    object.

    *obj* is the Python object to be documented, and *parent* is an
    another Python object (e.g. a module or a class) to which *obj*
    belongs to.
    r   )DataDocumenterModuleDocumenterNr0    c                   s    g | ]}|  d dr|qS )rl   F)Zcan_document_member).0clsrh   Z
parent_docr3   r4   
<listcomp>   s    z"get_documenter.<locals>.<listcomp>c                 S  s   | j S r;   )priority)rn   r3   r3   r4   <lambda>       z get_documenter.<locals>.<lambda>)keyr>   )sphinx.ext.autodocrj   rk   inspectismoduleget_documenterhasattrr[   r0   rY   Zdocumentersvaluessort)rb   rh   ri   rj   rk   Zparent_doc_clsclassesr3   ro   r4   rx      s    

rx   c                   @  s   e Zd ZU dZdZdZdZdZej	ej
ejejej
dZded< dd	d
dZddddddZddddddddZdddddZdddddZd S )!Autosummaryz
    Pretty table containing short signatures and summaries of functions etc.

    autosummary can also optionally generate a hidden toctree:: node.
    r   FT)captiontoctreenosignatures	recursivetemplater,   option_specz
list[Node]rS   c                 C  s  t | j| jjjt | j| j| _dd | jD }| 	|}| 
|}d| jkrlt| jj}| jd  }g }t| jj}| jj}|D ]\}	}
}}|||}t||}tt||}|| jjkr|| j|drtd}ntd}tj|||  d q|| q|rlt }||d< d	d |D |d
< d|d< d |d< | jd|d< |t dd| d| jkrd| jkrtjtd|d d |S )Nc                 S  s8   g | ]0}|  rtd |  d r|   d qS )z^[~a-zA-Z_]r   )stripresearchsplitrm   xr3   r3   r4   rp      s     z#Autosummary.run.<locals>.<listcomp>r   Fz5autosummary references excluded document %r. Ignored.zMautosummary: stub file not found %r. Check your autosummary_generate setting.locationZincludefilesc                 S  s   g | ]}d |fqS r;   r3   )rm   Zdocnr3   r3   r4   rp     s     entriesr>   Zmaxdepthglobr~   rl   z;A captioned autosummary requires :toctree: option. ignored.)!r   rc   rd   r_   reporterr   linenobridgecontent	get_items	get_tableoptions	posixpathdirnamedocnamer   r+   rW   Zexclude_patternsautosummary_filename_mapgetjoinnormpath
found_docsdoc2pathr   loggerwarningget_locationappendr   r   r.   )r6   namesitemsr
   r   Ztree_prefixZdocnamesexcludedZfilename_map_nameZ_sigZ_summary	real_namer   msgZtocnoder3   r3   r4   run   sL      



zAutosummary.runstrlist[str | None]tuple[str, Any, Any, str]nameprefixesr8   c                 C  s   t | jj zt||W W  5 Q R  S  tk
r } zzz t||W  W Y fW  5 Q R  S  tk
r } z6|jr|j|jg }n|j|g }t|j	d |W 5 d }~X Y nX W 5 d }~X Y nX W 5 Q R X d S )Nr   )
r   rW   autosummary_mock_importsimport_by_nameImportExceptionGroupimport_ivar_by_nameImportError	__cause__
exceptionsargs)r6   r   r   excZexc2errorsr3   r3   r4   r     s     zAutosummary.import_by_namer   r   r   )rb   rh   ri   	full_namer8   c                 C  s   t |||}|| j|S )zGet an autodoc.Documenter class suitable for documenting the given
        object.

        Wraps get_documenter and is meant as a hook for extensions.
        )rx   r   )r6   rb   rh   ri   r   Zdocclsr3   r3   r4   create_documenter   s    zAutosummary.create_documenter	list[str]zlist[tuple[str, str, str, str]])r   r8   c                 C  sf  t | j}g }d}|D ]H}|}|drD|dd }|dd }z| j||d\}}}	}
W n^ tk
r } z@tdd	 |jD }tj	t
d
|d||  d W Y qW 5 d}~X Y nX t | j_|}t|ts|
d |t|
d d  }| | jj||	|}| s<tj	t
d||  d ||dd|f q| srtj	t
d||  d ||dd|f qzt| |_|j  W n6 tk
r } ztd| d|_W 5 d}~X Y nX z|jdd}W n t k
r   | }Y nX |sd}nt!d|t| }t"||d}d|_#|$d t%| jjj&dd | j'j(}|||||f q|S )z}Try to import the given names, and return a list of
        ``[(name, signature, summary_string, real_name), ...]``.
        2   ~   N.r>   )r   c                 S  s"   h | ]}d t |j d| qS )z* z: )typer0   rm   er3   r3   r4   	<setcomp>=  s     z(Autosummary.get_items.<locals>.<setcomp>z4autosummary: failed to import %s.
Possible hints:
%s
r   z::zfailed to parse name %srl   zfailed to import object %sz$[autodoc] module analyzer failed: %sF)Zshow_annotation
   	max_chars))get_import_prefixes_from_envrc   
startswithr   r   r   rH   r   r   r   r   r   r   r   r   resultrI   r   lenr   rb   
parse_namer   Zimport_objectr   
for_moduleZget_real_modnameanalyzerZfind_attr_docsr    debugZformat_signature	TypeErrormaxmangle_signatureZ_extra_indentZadd_contentextract_summarydatard   r_   )r6   r   r   r   Zmax_item_charsr   display_namer   rh   ri   modnamer   r   r   Z
documentererrsigr   summaryr3   r3   r4   r   *  sp    



  




zAutosummary.get_items)r   r8   c                   s  t  }d|d< td}tjddgd}|| tjddd}|| |tjddd	 |tjdd
d	 td |  ddd fdd}|D ]d\}}}	}
d}dj	krd| d| d|
 dt
| }nd| d| d|
 d}|	}||| q||gS )zGenerate a proper list of table nodes for autosummary:: directive.

        *items* is a list produced by :meth:`get_items`.
        z\X{1}{2}\X{1}{2}specrl   zautosummary longtabler|      )colsr   )colwidthZ   r   r5   )column_textsr8   c               
     s   t d}j \}}| D ]}t d}t }||d||f  tj|Z j	|d| zt
|d t jr||d }W n tk
r   Y nX |t d| W 5 Q R X q | d S )Nrl   z%s:%d:<autosummary>r   )r
   rD   state_machineZget_source_and_linerF   r   r   r(   rd   Znested_parserI   rM   rE   )r   rD   sourcelinetextr7   Zvlbodyr6   r3   r4   
append_row  s    

z)Autosummary.get_table.<locals>.append_rowrh   r   z:py:z:`z <z>`\ z>`)r   Ztabular_col_specr=   r
   rA   r   rB   ZcolspecrC   r   r#   escape)r6   r   Z
table_specrA   Z
real_tablegroupr   r   r   r   r   Z	qualifierZcol1Zcol2r3   r   r4   r   |  s(    




$zAutosummary.get_tableN)r0   r1   r2   __doc__Zrequired_argumentsZoptional_argumentsZfinal_argument_whitespaceZhas_contentr   Zunchanged_requiredZ	unchangedflagr   __annotations__r   r   r   r   r   r3   r3   r3   r4   r}      s    
0
Rr}   r   )sr8   c                 C  s   |  dd  S )z+Strip a type hint from argument definition.:r   )r   r   )r   r3   r3   r4   strip_arg_typehint  s    r   c                 C  s   z|t | }t|j }t|D ]B\}}|jtjk	rB|jtjd}|j	tjk	rZ|jdd}|||< q |j|tjd}t
|W S  tk
r   |  Y S X dS )zCClean up signature using inspect.signautre() for mangle_signature())
annotationN)default)
parametersreturn_annotation)r*   rH   r   rz   rG   r   r   emptyrL   r   r   	Exception)r   r   r   iparamr3   r3   r4   _cleanup_signature  s    

r      int)r   r   r8   c           
      C  s  t | }tdd|}tdd| }tdd|}tdd|}tdd|}td	d|}td
d|}td|rtdd|}qntd|rtdd|}qtd|rtdd|}qg }g }td}|r||}|s|d}q|d|d |ddd }qt	|D ]\}}t
|||< q$t	|D ]\}}	t
|	||< qDtd||d d} |r| sdtd||d d } n@t| |d d d k r| dtd||t|  d d d 7 } d|  S )z5Reformat a function signature to a more compact form.z\)\s*->\s.*$)z
^\((.*)\)$z\1z\\\\rl   z\\'z\\"z'[^']*'z"[^"]*"z	\([^)]*\)z<[^>]*>z{[^}]*}z^(.*, |)([a-zA-Z0-9_*]+)\s*=\s*z, r   r   r   Nr   z[%s]      z[, %s]z(%s))r   r   subr   r   compiler   insertr   rG   r   limited_joinr   )
r   r   r   r   optsZopt_remr   argoptr3   r3   r4   r     sJ    




r   r   )docr_   r8   c                 C  s\  dddddd}| r.| d   s.| d qt| D ] \}}|  s6| d| }  qXq6| g krdd	S || |j}t|d tjr|d    }nt|d tjs| d   }nt	
d
| }t|dkr|d   }nrd	}tt|D ]`}d|d|d  dd }g |dd< || |j}|tr4qt|tjs qLqtd|}|S )zExtract summary from docstring.r   r   znodes.document)r  r]   r8   c                 S  s,   t td}td|}t |_|| | |S )NZBodyrl   )r   r   r'   r$   r   r   )r  r]   r   r7   r3   r3   r4   parse  s
    

zextract_summary.<locals>.parser   Nrl   r?   r   z. r   )r   poprG   r]   rI   r
   sectionrK   rF   
periods_rer   r   r   rangerstripendswithWELL_KNOWN_ABBREVIATIONSanyfindallr   
literal_rer   )r  r_   r  r   Zpiecer7   r   Z	sentencesr3   r3   r4   r     s8    	 r   ...)sepr   r   overflow_markerr8   c                 C  sz   |  |}t||k r|S d}d}|D ]6}|t|t|  7 }||t| k rX|d7 }q& q^q&|  t|d| |g S )zJoin a number of strings into one, limiting the length to *max_chars*.

    If the string overflows this limit, replace the last fitting item by
    *overflow_marker*.

    Returns: joined_string
    r   r   N)r   r   rH   )r  r   r   r  Zfull_strZn_charsZn_itemsitemr3   r3   r4   r  7  s    	

r  c                      s(   e Zd ZdZddd fddZ  ZS )r   zExceptions raised during importing the target objects.

    It contains an error messages and a list of exceptions as its arguments.
    
str | NonezSequence[BaseException])messager   c                   s   t  | t|| _d S r;   )ra   rZ   rH   r   )r6   r  r   re   r3   r4   rZ   Y  s    zImportExceptionGroup.__init__)r0   r1   r2   r   rZ   rg   r3   r3   re   r4   r   S  s   r   r   r   )rc   r8   c                 C  s\   dg}| j d}|r"|d| | j d}|rX|rL|d|d |  n|d| |S )z`
    Obtain current Python import prefixes (for `import_by_name`)
    from ``document.env``
    Nz	py:moduler   zpy:classr   )Zref_contextr   r  )rc   r   Z
currmoduleZ	currclassr3   r3   r4   r   ^  s    r   r   r   c                 C  s   g }g }|D ]}z<|r&d || g}n| }t|dd\}}}||||fW   S  tk
rj   || Y q tk
r }	 z|| ||	 W 5 d}	~	X Y qX qtdd |D g }
tdd | |
dS )	z~Import a Python object that has the given *name*, under one of the
    *prefixes*.  The first name that succeeds is used.
    r   T)grouped_exceptionNc                 s  s   | ]}|j V  qd S r;   )r   r   r3   r3   r4   	<genexpr>  s     z!import_by_name.<locals>.<genexpr>zno module named %sz or )r   _import_by_namer   r   r   sum)r   r   Ztriedr   prefixZprefixed_namerh   ri   r   r   r   r3   r3   r4   r   s  s     
r   Tboolztuple[Any, Any, str])r   r  r8   c                 C  s  g }zd|  d}d|dd }|rz t|}t||d ||fW W S  tttfk
r } z||jpl| W 5 d}~X Y nX d}d}t	t
dt|d D ]j}|}d|d| }zt| W n2 tk
r } z||jp| W 5 d}~X Y nX |tjkr qq|t|k rVd}	tj| }
||d D ]}|
}	t|
|}
q4|
|	|fW S tj| d|fW S W nT ttttfk
r } z,|| |rtd|nt|j |W 5 d}~X Y nX dS )z+Import a Python object given its full name.r   Nr>   r   r   rl   )r   r   r   getattrr   rM   AttributeErrorr   r   reversedr  r   sysmodules
ValueErrorKeyErrorr   r   )r   r  r   Z
name_partsr   modr   Zlast_jrO   ri   rh   obj_namer3   r3   r4   r    sD    
""


r  )r   r   r  r8   c              
   C  s   z|  dd\} }t| |\}}}}t|}t|dkr>|f}|D ]n}	tt|	d|}
|
  t }|dd |
j	D O }|dd |
j
D O }||krB|d | t||f  W S qBW nB tttfk
r } z
t|W 5 d}~X Y n tk
r    Y nX tdS )	zImport an instance variable that has the given *name*, under one of the
    *prefixes*.  The first name that succeeds is used.
    r   r   r   r1   c                 S  s   h | ]\}}|qS r3   r3   rm   qualnameattrr3   r3   r4   r     s     z&import_ivar_by_name.<locals>.<setcomp>c                 S  s   h | ]\}}|qS r3   r3   r(  r3   r3   r4   r     s     N)rsplitr   r)   r   r   r   r  ZanalyzesetZ	attr_docsr   r   r   r$  r    r   )r   r   r  r*  r   rh   ri   r   Zcandidate_objectsZcandidate_objr   Zfound_attrsr   r3   r3   r4   r     s&     r   c                   @  s   e Zd ZdZddddZdS )AutoLinkzSmart linking role.

    Expands to ':obj:`text`' if `text` is an object that can be imported;
    otherwise expands to '*text*'.
    z'tuple[list[Node], list[system_message]]rS   c                 C  s   | j dd}|d| j| j| j| j| j| j\}}|rB||fS t	|dksRt
ttj|d }zt| j }t|d | W nB tk
r   ttj|d }tj| j| |d d|d< Y nX ||fS )Npyrh   r   r   Z	reftargetr|   r   )rc   Z
get_domainZroleZrawtextr   r   Zinlinerr   r   r   AssertionErrorr	   r   pending_xrefr   r   r   r
   literalZemphasisrK   )r6   Z
pyobj_roleobjectsr   r0  r   r1  r3   r3   r4   r     s&      
zAutoLink.runN)r0   r1   r2   r   r   r3   r3   r3   r4   r-    s   r-  r  )rb   r8   c                   s>   ddd fdd}d } j jD ]}d||kr |  S q d S )Nr   ztuple[str, ...])suffixr8   c                   s"    j  | }|d krdS |jS )N)restructuredtext)rY   Zget_source_parsersr   	supported)r3  parser_classrb   r3   r4   get_supported_format  s    z,get_rst_suffix.<locals>.get_supported_formatr4  )rW   source_suffix)rb   r8  r3  r3   r7  r4   get_rst_suffix  s    
r:  c              
     s  | j j}|dkr.| jj  fdd jD }nh|dkr8n^t| j jfdd|D }|d d  D ]2}tt	| j
|sbttd| || qb|sd S t| }|d krttd d S dd	lm} | j j}t| j j& |||| j
| || j j| j jd
 W 5 Q R X d S )NTc                   s,   g | ]$}t j |r j|d dqS )F)base)osr   isfiler   r   )rc   r3   r4   rp     s    z,process_generate_options.<locals>.<listcomp>Fc                   s*   g | ]"}|| t s  d  nd qS )r   rl   )r  tuple)rm   Zgenfile)extr3   r4   rp     s   z(autosummary_generate: file not found: %szbautosummary generats .rst files internally. But your source_suffix does not contain .rst. Skipped.r   )generate_autosummary_docs)r3  	base_pathrb   imported_members	overwriteencoding)rW   autosummary_generateZbuilderrc   r   rH   r9  r   r=  r   rV   r   r   r   remover:  Zsphinx.ext.autosummary.generater@  autosummary_imported_membersr   r   autosummary_generate_overwriteZsource_encoding)rb   ZgenfilesrE   r3  r@  rB  r3   )rc   r?  r4   process_generate_options  s:    

 rI  zdict[str, Any]c                 C  s  |  d | jtttfttfttfttfttfd | jtttfttfttfttfttfd | dt | 	dt
  | dt | di d | di d	 | d
ddttg | ddd | ddd d | dg dtg | dddt tjddS )Nzsphinx.ext.autodoc)htmllatexr   manZtexinfoZautosummaryZautolinkzbuilder-initedZautosummary_contextTr   rJ  rE  rH  Fr   c                 S  s   | j S r;   )Zautodoc_mock_imports)rW   r3   r3   r4   rr   E  rs   zsetup.<locals>.<lambda>rc   rG  Zautosummary_ignore_module_all)versionZparallel_read_safe)Zsetup_extensionadd_noder.   r:   r<   r=   rQ   Zadd_directiver}   Zadd_roler-  connectrI  Zadd_config_valuer  rH   sphinxZ__display_version__r7  r3   r3   r4   setup.  s:    
 rQ  )r   )r   r  )T)mr   
__future__r   rv   r<  r   r   r"  r   r   typesr   typingr   r   r   r	   Zdocutilsr
   Zdocutils.nodesr   r   Zdocutils.parsers.rstr   Zdocutils.parsers.rst.statesr   r   r   Zdocutils.statemachiner   rP  r   Zsphinx.applicationr   Zsphinx.configr   Zsphinx.environmentr   ru   r   r   Zsphinx.ext.autodoc.directiver   r   Zsphinx.ext.autodoc.importerr   Zsphinx.ext.autodoc.mockr   Zsphinx.extensionr   Zsphinx.localer   Zsphinx.projectr   Zsphinx.pycoder   r    Zsphinx.registryr!   Zsphinx.utilr"   r#   Zsphinx.util.docutilsr$   r%   r&   r'   r(   Zsphinx.util.inspectr)   r*   Zsphinx.util.matchingr+   Zsphinx.util.typingr,   Zsphinx.writers.htmlr-   	getLoggerr0   r   r   r  r  r  commentr.   r:   r<   r=   rQ   rR   r[   rx   r}   r   r   r   r   r  r   r   r   r   r  r   r-  r:  rI  rQ  r3   r3   r3   r4   <module>   s   0


% a;8  /"&