o
    Nin                     @  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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mZmZ ddlmZ ddlmZ ddlZdd	lmZmZ dd
lmZ ddlmZ ddlm Z  ddl!m"Z" ddl#m$Z$m%Z%m&Z&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l0m1Z1m2Z2 ddl3m4Z4 ddl5m6Z6 erddl7m8Z8m9Z9 ddl:m;Z; ddl<m=Z= ddl>m?Z? e.@eAZBG dd dZCG dd deZDdd"d#ZEddd(d)ZFG d*d+ d+ZGdd.d/ZHG d0d1 d1ZIdd6d7ZJ		dddCdDZKddGdHZLddIdJZMddKdLZNddOdPZOeP dQdRddYdZZQdd\d]ZRdd^ddbdcZS		d		e		Q	fdddqdrZTddudvZU	dddxdyZV		ddd|d}ZWdddZXddddZYeAdkrneYejZdd  dS dS )ax  Generates reST source files for autosummary.

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
    )annotationsN)path)Path)TYPE_CHECKINGAny
NamedTuple)TemplateNotFound)SandboxedEnvironment)__display_version__package_dir)Builder)Config)PycodeError)import_module)ImportExceptionGroupget_documenterimport_by_nameimport_ivar_by_name)__)ModuleAnalyzer)SphinxComponentRegistry)loggingrst)getallsafe_getattr)	ensuredir)SphinxTemplateLoader)SequenceSet)NullTranslations)Sphinx)
Documenterc                   @  s$   e Zd ZdZdddZdd
dZdS )DummyApplicationz3Dummy Application class for sphinx-autogen command.
translatorr   returnNonec                 C  sn   t  | _t | _g | _d| _|| _d| _d| _d| _	| j
di dd | j
di dd | j
dd	dt d S )
N/r   Fautosummary_contextenv autosummary_filename_mapautosummary_ignore_module_allT)r   configr   registry
messagelogsrcdirr#   	verbosity
_warncount_exception_on_warningaddbool)selfr#   r)   r)   S/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/ext/autosummary/generate.py__init__B   s   zDummyApplication.__init__argsr   c                 G  s   d S Nr)   )r5   r8   r)   r)   r6   emit_firstresultP   s   z!DummyApplication.emit_firstresultN)r#   r   r$   r%   )r8   r   r$   r%   )__name__
__module____qualname____doc__r7   r:   r)   r)   r)   r6   r"   ?   s    
r"   c                   @  s.   e Zd ZU ded< ded< ded< ded< dS )	AutosummaryEntrystrname
str | Noner   templater4   	recursiveN)r;   r<   r=   __annotations__r)   r)   r)   r6   r?   T   s
   
 r?   appr   r$   r%   c              	   C  s`   ddl m}m}m}m}m}m}m}m}m	}	 |||||||||	g	}
|
D ]
}| j
|j| q#d S )Nr   )	AttributeDocumenterClassDocumenterDataDocumenterDecoratorDocumenterExceptionDocumenterFunctionDocumenterMethodDocumenterModuleDocumenterPropertyDocumenter)sphinx.ext.autodocrG   rH   rI   rJ   rK   rL   rM   rN   rO   r-   add_documenterobjtype)rF   rG   rH   rI   rJ   rK   rL   rM   rN   rO   documenters
documenterr)   r)   r6   setup_documenters[   s   ,rU   =titler@   linec                 C  s(   d| v r
d}t || d |t|   S )N
zCan only underline single lines)
ValueErrorlen)rW   rX   msgr)   r)   r6   
_underlinew   s   r]   c                   @  s$   e Zd ZdZdddZdddZdS )AutosummaryRendererzA helper class for rendering.rF   r    r$   r%   c                 C  s   t |trd}t|tjtdddg}t|j|j	j
|}t|d| _tj| jjd< tj| jjd< t| jjd< |jrJ| jd	 | j|j d S d S )
Nz%Expected a Sphinx application object!extautosummary	templates)loaderescapee	underlinezjinja2.ext.i18n)
isinstancer   rZ   osr   joinr   r   r/   r,   templates_pathr	   r(   r   rc   filtersr]   r#   add_extensioninstall_gettext_translations)r5   rF   r\   system_templates_pathrb   r)   r)   r6   r7      s    
zAutosummaryRenderer.__init__template_namer@   contextdict[str, Any]c                 C  sb   z| j |}W n# ty+   z
| j d| }W n ty(   | j d}Y nw Y nw ||S )zRender a template file.zautosummary/%s.rstzautosummary/base.rst)r(   get_templater   render)r5   rn   ro   rC   r)   r)   r6   rr      s   
zAutosummaryRenderer.renderN)rF   r    r$   r%   )rn   r@   ro   rp   r$   r@   )r;   r<   r=   r>   r7   rr   r)   r)   r)   r6   r^   ~   s    
r^   rA   tuple[str | None, str]c              
   C  s   |  d}t|dD ]P\}}zd|d| }t| W q
 tyR   |d|d  rGd|d|d  d||d d f Y   S dd|f Y   S  tyZ   Y q
w | dfS )a  Split full qualified name to a pair of modname and qualname.

    A qualname is an abbreviation for "Qualified name" introduced at PEP-3155
    (https://peps.python.org/pep-3155/).  It is a dotted path name
    from the module top-level.

    A "full" qualified name means a string containing both module name and
    qualified name.

    .. note:: This function actually imports the module to check its existence.
              Therefore you need to mock 3rd party modules if needed before
              calling this function.
    .   N )split	enumeraterh   	importlibr   ImportError
IndexError)rA   partsi_partmodnamer)   r)   r6   _split_full_qualified_name   s   
4r   c                   @  s4   e Zd ZdddZdddZdddZdddZdS )ModuleScannerrF   r   objr$   r%   c                 C  s   || _ || _d S r9   )rF   object)r5   rF   r   r)   r)   r6   r7      s   
zModuleScanner.__init__rA   r@   valuec                 C  s   t | j|| jjS r9   )r   rF   r   rR   )r5   rA   r   r)   r)   r6   get_object_type   s   zModuleScanner.get_object_typerR   r4   c              
   C  sV   z| j d|||di W S  ty* } ztjtd||dd W Y d }~dS d }~ww Nzautodoc-skip-memberFz\autosummary: failed to determine %r to be documented, the following exception was raised:
%sr`   type)rF   r:   	Exceptionloggerwarningr   )r5   rA   r   rR   excr)   r)   r6   
is_skipped   s    	zModuleScanner.is_skippedimported_members	list[str]c           
   	   C  s"  g }zt | jj}| }W n ty   i }Y nw t| j| jjD ]k}zt	| j|}W n t
y8   d }Y nw | ||}| |||rGq#z!d|f|v rQd}nt|rYd}nt	|d| jjkred}nd}W n t
ys   d}Y nw | jjj }	|s|du s|	rdt| jv r|| q#|S )Nrv   FTr<   __all__)r   
for_moduler   r;   find_attr_docsr   
members_ofrF   r,   r   AttributeErrorr   r   inspectismoduler+   dirappend)
r5   r   membersanalyzer	attr_docsrA   r   rR   importedrespect_module_allr)   r)   r6   scan   sL   

zModuleScanner.scanN)rF   r   r   r   r$   r%   )rA   r@   r   r   r$   r@   )rA   r@   r   r   rR   r@   r$   r4   )r   r4   r$   r   )r;   r<   r=   r7   r   r   r   r)   r)   r)   r6   r      s
    


r   r   confr   Sequence[str]c                 C  s   |j rt| S t| pt| S )zGet the members of ``obj``, possibly ignoring the ``__all__`` module attribute

    Follows the ``conf.autosummary_ignore_module_all`` setting.
    )r+   r   r   )r   r   r)   r)   r6   r     s   r   parentrC   rn   r   r4   rD   ro   rp   r   rB   qualnamec                 C  s  t |||}i }|| |jdkrt||}|||d< |jj }|p,dt|v o,|}t|||dh|d\|d< |d< t|||dh|d\|d	< |d
< t|||dh|d\|d< |d< t	| |d \|d< |d< t
|d}|r|r|d |d
  |d  |d  }|rdt|v rt|||dhdd\}}||7 }t|}ng g }}d }t||| |d\}}|| |d< || |d< n:|jdkrt||d< tt|t|j  |d< t|||dhdhd\|d< |d< t|||ddh\|d< |d< |	d u s|
d u rt| \}	}
|jdv r|
ddd  |d< |jdkr!|
}n|
ddd! }| |d"< |	|d< |
|d#< ||d$< |j|d%< t| d& |d'< |rO|||S ||j|S )(Nmoduler   r   function)r   	functionsall_functionsclassclassesall_classes	exception
exceptionsall_exceptions
attributesall_attributes__path__T)skiprA   public_membersmodulesall_modulesinherited_membersmethodr7   )include_publicmethodsall_methods	attributeproperty)r   r   r   rt   ru   r   fullnameobjnamerA   rR   rV   re   )r   updaterR   r   r   r,   r+   r   _get_members_get_module_attrshasattrr   _get_modulesset__dict__keysr   rsplitr[   rr   )rA   r   r   rC   rn   r   rF   rD   ro   r   r   docnsscannerr   	ispackager   imported_modulesall_imported_modulesr   r   r   	shortnamer)   r)   r6   generate_autosummary_content  s   










r   r    rR   c              
   C  sT   z|  d|||di W S  ty) } ztjtd||dd W Y d }~dS d }~ww r   )r:   r   r   r   r   )rF   r   rA   rR   r   r)   r)   r6   _skip_member  s    	r   c                 C  s&   t jjj| d t}dd | D S )Nc                 S  s   i | ]\}}||j qS r)   )r   ).0rA   memberr)   r)   r6   
<dictcomp>  s    z&_get_class_members.<locals>.<dictcomp>)sphinxr_   autodocimporterget_class_membersr   items)r   r   r)   r)   r6   _get_class_members  s   r   c              	   C  s>   i }t || jD ]}z	t||||< W q ty   Y qw |S r9   )r   r,   r   r   )rF   r   r   rA   r)   r)   r6   _get_module_members  s   r   r   type[Documenter]c                 C  s*   | j dkr
t||S | j dkrt|S i S )Nr   r   )rR   r   r   )r   rF   r   r)   r)   r6   _get_all_members  s
   


r   T)r   r   typesset[str]r   Set[str]r   tuple[list[str], list[str]]c                C  s   g }g }t | ||}| D ]I\}	}
t||
|}|j|v rW|s(t|
dd |jkrWt||
|	|j}|du r5q|du rD||	 ||	 q||	 |	|v sR|	dsW||	 q||fS )Nr<   TF_)	r   r   r   rR   getattrr;   r   r   
startswith)r   rF   r   r   r   r   r   publicall_membersrA   r   rT   skippedr)   r)   r6   r     s$   	



r   r   c                 C  s|   g g }}z,t | }| }|D ]\}}|dkr,||v r,|| |ds,|| qW ||fS  ty=   Y ||fS w )z'Find module attributes with docstrings.rv   r   )r   r   r   r   r   r   )rA   r   attrsr   r   r   	namespace	attr_namer)   r)   r6   r     s    




r   )r   r   r   Sequence[str] | Nonec             	   C  s   g }g }t | jD ]F\}}}||v rq
| d| }	zt|	}
W n	 ty*   Y n	w |
r3t|
dr3q
|| |d urF||v rE|| q
|dsP|| q
||fS )Nrt   __sphinx_mock__r   )pkgutiliter_modulesr   r   rz   r   r   r   )r   r   rA   r   r   r   r   r   _ispkgr   r   r)   r)   r6   r     s,   



r   .rstFutf-8sourcesr   
output_dirstr | os.PathLike[str] | Nonesuffix	base_pathSphinx | None	overwriteencoding
list[Path]c                   s0  |dusJ dt | }t|dkr!|dd dg |dd  }ttdd| |r6ttd	|  durC fd
d| D } t|}	t| }
g }g }|jj	}t t
|
tdD ]#}|jdu rdq[|pltj|j}t| zt|j\}}}}||d d}W nf ty } zZzt|j\}}}}||d d}W n@ ty } z4|jrg |j|j}ng |j|}tdd |D }ttd|jd| W Y d}~W Y d}~q[d}~ww W Y d}~nd}~ww i |jj}t||||	|j|||j|||}t||||| }| | |! r]|j"|d}|# }W d   n	1 s,w   Y  ||kr7q[|r\|j"d|d}|$| W d   n	1 sRw   Y  | | q[t"|d|d}|$| W d   n	1 suw   Y  | | q[|r|%t&dd |D || |||d |S )zGenerate autosummary documentation for the given sources.

    :returns: list of generated files (both new and existing ones)
    Nzapp is required   
   z...iz,[autosummary] generating autosummary for: %sz, z[autosummary] writing to %sc                   s   g | ]	}t j |qS r)   )rg   r   rh   )r   filenamer   r)   r6   
<listcomp>  s    z-generate_autosummary_docs.<locals>.<listcomp>)keyrt   rv   c                 S  "   h | ]}d t |j d| qS z* z: r   r;   r   rd   r)   r)   r6   	<setcomp>9     " z,generate_autosummary_docs.<locals>.<setcomp>z5[autosummary] failed to import %s.
Possible hints:
%srY   )r   wc                 S  s   g | ]}t |qS r)   )r@   )r   fr)   r)   r6   r   f  s    )r   r   r   r   rF   r   )'sortedr[   r   infor   rh   r^   find_autosummary_in_filesr,   r*   r   r@   r   rg   abspathr   r   rA   replacer   r   rz   	__cause__r   listr   r'   r   rC   rD   r   getr   is_fileopenreadwriteextendgenerate_autosummary_docs)r   r   r   r   r   rF   r   r   showed_sourcesrC   r   	new_files	all_filesfilename_mapentryr   rA   r   r   r   r   r   exc2r   errorsro   content	file_pathr  old_contentr)   r   r6   r    s   





r  	filenameslist[AutosummaryEntry]c              	   C  s^   g }| D ](}t |ddd}|  }|t||d W d   n1 s'w   Y  q|S )z^Find out what items are documented in source/*.rst.

    See `find_autosummary_in_lines`.
    r   ignore)r   r  r   N)r  r  
splitlinesr  find_autosummary_in_lines)r  
documentedr   r  linesr)   r)   r6   r	  v  s   r	  r   c           	   
   C  s   zt | \}}}}t| }t|| |dW S  ty!   Y g S  tyI } zddd |jD }t	
d|  d|  W Y d}~g S d}~w tyX   t	
d|  Y g S w )	znFind out what items are documented in the given object's docstring.

    See `find_autosummary_in_lines`.
    )r   r   rY   c                 S  r   r   r  r  r)   r)   r6   r    r  z0find_autosummary_in_docstring.<locals>.<setcomp>zFailed to import z.
Possible hints:
Nz_Failed to import '%s'; the module executes module level statement and it might call sys.exit().)r   pydocgetdocr#  r$  r   r   rh   r   r   r   
SystemExit)	rA   r   	real_namer   r   r   r&  r   r  r)   r)   r6   find_autosummary_in_docstring  s&   
 r+  r&  r   c                 C  s  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}|rZtjtj||}q3|	|}|rj|d }q3| 	drrq3||}|r|d 
d}|r|	|d s| d| }|
t|||| q3| r|	|d rq3d}||}|rd}|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*$FNrv   Tru   :~rt    r"     )recompilematchgrouprg   r   rh   dirnamestripr   removeprefixr   r?   searchr  r+  )r&  r   r   autosummary_reautomodule_re	module_reautosummary_item_rerecursive_arg_retoctree_arg_retemplate_arg_rer%  rD   toctreerC   current_modulein_autosummarybase_indentrX   mrA   r)   r)   r6   r$    s~   

















r$  argparse.ArgumentParserc                  C  s   t jdtdtdd} | jddddt d	 | jd
dtdd | jddddtdd | jdddddtdd | jddddd tdd | jddd d!d"td#d | jd$d%d d&d"td'd | jd(d d)d"td*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destrH  source_file+z&source files to generate rST files for)nargshelpz-oz--output-dirstorer   z directory to place all output in)rJ  rK  rO  z-sz--suffixr   r   z/default suffix for files (default: %(default)s))rJ  rK  defaultrO  z-tz--templatesra   z0custom template directory (default: %(default)s)z-iz--imported-members
store_truer   Fz0document imported members (default: %(default)s)z-az--respect-module-allr   zPdocument exactly the members in module __all__ attribute. (default: %(default)s)z--remove-old
remove_oldzERemove existing files in the output directory that were not generated)argparseArgumentParserr   add_argumentr
   )parserr)   r)   r6   
get_parser  s   

rX  r)   argvc                C  s  t t jd tj   ttj  }t|t	j
t	j t| t | p+t	jdd  }|jr;|jjt|j |j |j_t|j|jd|j |j|d}|jrt|jd|j D ]-}||vrz|   W q_ t!y } zt"j#t$d||j%dd W Y d }~q_d }~ww q_d S d S )	Nrv   ru   rt   )r   rF   z**/*.zFailed to remove %s: %sr`   r   )&locale	setlocaleLC_ALLr   init_consoler"   get_translatorr   setupsysstdoutstderrrU   rX  
parse_argsrY  ra   r,   ri   r   r   r
  r   r+   r  rL  r   r   r   rS  r   globunlinkOSErrorr   r   r   strerror)rY  rF   r8   written_filesexistingr   r)   r)   r6   mainN  sB   
rj  __main__ru   )rF   r   r$   r%   )rV   )rW   r@   rX   r@   r$   r@   )rA   r@   r$   rs   )r   r   r   r   r$   r   )NN)rA   r@   r   r   r   r   rC   r^   rn   r@   r   r4   rF   r   rD   r4   ro   rp   r   rB   r   rB   r$   r@   )
rF   r    r   r   rA   r@   rR   r@   r$   r4   )r   r   r$   rp   )rF   r    r   r   r$   rp   )r   r   rF   r    r   r   r$   rp   )r   r   rF   r    r   r   r   r   r   r   r   r4   r$   r   )rA   r@   r   r   r$   r   )
r   r   r   r   rA   r@   r   r   r$   r   )Nr   NFNTr   )r   r   r   r   r   r@   r   r   r   r4   rF   r   r   r4   r   r@   r$   r   )r  r   r$   r   r9   )rA   r@   r   rB   r$   r   )r&  r   r   rB   r   rB   r$   r   )r$   rD  )r)   )rY  r   r$   r%   )[r>   
__future__r   rT  ry   r   rZ  rg   r   r'  r0  r`  r   pathlibr   typingr   r   r   jinja2r   jinja2.sandboxr	   sphinx.localer   r
   r   sphinx.buildersr   sphinx.configr   sphinx.errorsr   sphinx.ext.autodoc.importerr   sphinx.ext.autosummaryr   r   r   r   r   sphinx.pycoder   sphinx.registryr   sphinx.utilr   r   sphinx.util.inspectr   r   sphinx.util.osutilr   sphinx.util.templater   collections.abcr   r   gettextr   sphinx.applicationr    rP   r!   	getLoggerr;   r   r"   r?   rU   r]   r^   r   r   r   r   r   r   r   r   	frozensetr   r   r   r  r	  r+  r$  rX  rj  rY  r)   r)   r)   r6   <module>   s    


(!
E
h




!"
}
]T
#