o oa`@s8dZddlZddlZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddlm Z ddl mZmZmZmZmZmZmZmZddlmZddlmZddlZddlmZmZdd lmZdd l m!Z!dd l"m#Z#dd l$m%Z%dd l&m'Z'ddl(m)Z)ddl*m+Z+m,Z,m-Z-ddlm.Z.ddl/m0Z0m1Z1ddl2m3Z3ddl4m5Z5m6Z6m7Z7ddl8m9Z9ddl:m;Z;ddle?Z@GdddZAGdddeZBdeddfddZCdeDddfd d!ZEdeDddfd"d#ZFdXd%eDd&eDdeDfd'd(ZGGd)d*d*ZHGd+d,d,ZI dYd-eDd.ed/ed0eHd1eDd2eJded3eJd4ed5eDd6eDdeDfd7d8ZK     eDd?eDd@eDdAe!dBeDd2eJdedCeJdDeDddfdEdFZLdGeeDdeeBfdHdIZMdYd-eDdJeDdKeDdeeBfdLdMZNdYdNeeDdJeDdKeDdeeBfdOdPZOdejPfdQdRZQejRdSdfdTeeDddfdUdVZSe?dWkreSdSdS)[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)AnyDictList NamedTupleSetTupleTypeUnion)TemplateNotFound)SandboxedEnvironment)__display_version__ package_dir)Sphinx)Builder)Config)RemovedInSphinx50Warning) Documenter) import_module)get_documenterimport_by_nameimport_ivar_by_name)__)ModuleAnalyzer PycodeError)SphinxComponentRegistry)loggingrstsplit_full_qualified_name) safe_getattr) ensuredir)SphinxTemplateLoaderc@s4eZdZdZdeddfddZdeddfdd ZdS) DummyApplicationz3Dummy Application class for sphinx-autogen command. translatorreturnNcCsft|_t|_g|_d|_||_d|_d|_d|_ |j didd|j didd|j dS)N/rFautosummary_contextTautosummary_filename_map) rconfigrregistry messagelogsrcdirr$ verbosity _warncountwarningiserroradd init_values)selfr$r3A/usr/lib/python3/dist-packages/sphinx/ext/autosummary/generate.py__init__;szDummyApplication.__init__argscGsdSNr3)r2r6r3r3r4emit_firstresultIsz!DummyApplication.emit_firstresult)__name__ __module__ __qualname____doc__rr5rr8r3r3r3r4r#8sr#c@s.eZdZUeed<eed<eed<eed<dS)AutosummaryEntrynamertemplate recursiveN)r9r:r;str__annotations__boolr3r3r3r4r=Ms  r=appr%c Cslddlm}m}m}m}m}m}m}m}m } m } m } ||||||| | ||| g } | D] } |j | j| q)dS)Nr) AttributeDocumenterClassDocumenterDataDocumenterDecoratorDocumenterExceptionDocumenterFunctionDocumenterMethodDocumenterModuleDocumenterNewTypeAttributeDocumenterNewTypeDataDocumenterPropertyDocumenter)sphinx.ext.autodocrErFrGrHrIrJrKrLrMrNrOr*add_documenterobjtype)rDrErFrGrHrIrJrKrLrMrNrO documenters documenterr3r3r4setup_documentersTs4rUmsgcCstjdtddt|dS)Nz_simple_info() is deprecated. stacklevel)warningswarnrprintrVr3r3r4 _simple_infocs r^cCs&tjdtddtd|tjddS)Nz_simple_warn() is deprecated.rWrXz WARNING: )file)rZr[rr\sysstderrr]r3r3r4 _simple_warnisrb=titlelinecCs$d|vrtd|d|t|S)N zCan only underline single lines) ValueErrorlen)rdrer3r3r4 _underlineosric@sXeZdZdZddeeefdeddfddZdede fd d Z ded e defd d Z dS)AutosummaryRendererzA helper class for rendering.NrD template_dirr%cCst|tr tjdtdd|rtjdtddtjtdddg}t |j |j j |}t |d|_tj|jjd <tj|jjd <t|jjd <t|ttfr_|jr]|jd |j|jdSdSt|trx|jjrz|jd |j|jjdSdSdS) NzLThe first argument for AutosummaryRenderer has been changed to Sphinx objectrWrXzvaluecCst|j||jjSr7)rrDrrR)r2r>rr3r3r4get_object_typeszModuleScanner.get_object_typerRc CsVz |jd|||diWSty*}ztjtd||ddWYd}~dSd}~wwNzautodoc-skip-memberFz\autosummary: failed to determine %r to be documented, the following exception was raised: %srm)type)rDr8 Exceptionloggerwarningr)r2r>rrRexcr3r3r4 is_skippeds  zModuleScanner.is_skippedimported_membersc Csg}t|jD]Y}zt|j|}Wn tyd}Ynw|||}||||r+qzt|r4d}nt|d|jjkr@d}nd}Wn tyNd}Ynw|rW| |q|dur`| |q|S)NTr:F) dirrr AttributeErrorrrinspectismoduler9append)r2rmembersr>rrRimportedr3r3r4scans4      zModuleScanner.scan) r9r:r;rr5rArrCrrrr3r3r3r4rs  rr>rparentr?r|rr@rmodnamequalnamec st||dtdtdtdtffdd dtdtttfffdd dtdtttffd d dtdtttfffd d gd fdtdttdttdtdtttttff fdd } dtdtttttfffdd } dtdtttttfffdd } i}||j dkrt |}| ||d<| |dh|d\|d<|d<| |dh|d\|d<|d<| |d h|d\|d!<|d"<| |d\|d#<|d$<t |d%}|r|r| |\|d&<|d'<n6j dkr"t ||d<tt |t|j|d(<| |d)hd*g\|d+<|d,<| |d-d.h\|d#<|d$<| dus,dur2t\} j d/vrBd0d1d2|d<j d3vrK}nd0d1d4}|d5<| |d<|d6<||d<j |d<td7|d8<|ry|||S|j |S)9Nrr>rRr%c sTz d|||diWSty)}ztjtd||ddWYd}~dSd}~wwr)r8rrrr)rr>rRr)rDr3r4 skip_members  z1generate_autosummary_content..skip_membercs&tjj|gt}dd|DS)NcSsi|]\}}||jqSr3)r).0r>memberr3r3r4 szKgenerate_autosummary_content..get_class_members..)sphinxrlautodocget_class_membersr items)rr)rr3r4rsz7generate_autosummary_content..get_class_membersc Ss:i}t|D]}z t||||<WqtyYqw|Sr7)rr r)rrr>r3r3r4get_module_memberss  z8generate_autosummary_content..get_module_memberscs(jdkr |Sjdkr|SiS)Nmoduleclass)rR)r)docrrr3r4get_all_memberss  z5generate_autosummary_content..get_all_membersTtypesinclude_publicrc sg}g}|}|D]H\}}t||} | j|vrT|s&t|dd|jkrT||| j} | dur2q | durA||||q ||||vsO|dsT||q ||fS)Nr:TF_)rrrRgetattrr9r startswith) rrrrrpublic all_membersr>rrTskipped)rDrrr3r4 get_memberss$      z1generate_autosummary_content..get_membersrcs|gg}}z,t}|}|D]\}}|dkr,||vr,|||ds,||qW||fSty=Y||fSw)z'Find module attributes with docstrings.r)r for_modulefind_attr_docsrrr)rattrsranalyzer attr_docs namespace attr_namer>r3r4get_module_attrss       z6generate_autosummary_content..get_module_attrsc szg}t|jD])\}}}d|}zt|}|r!t|dr!WqWn ty+Ynw||qdd|D}||fS)N.__sphinx_mock__cSs$g|]}|ddds|qS)rr)splitr)rxr3r3r4 :s$zEgenerate_autosummary_content..get_modules..)pkgutil iter_modules__path__rhasattr ImportErrorr)rrrrispkgfullnamerrrr3r4 get_modules.s   z1generate_autosummary_content..get_modulesrfunction)r functions all_functionsrclasses all_classes exception exceptionsall_exceptions attributesall_attributesrmodules all_modulesinherited_membersmethodr5methods all_methods attributeproperty)rrrrr)rrrobjnamercrr)rrrArCrrrr updaterRrrrrset__dict__keysrrsplitrhr)r>rrr?r|rrDr@rrrrrrnsscanner ispackage shortnamer3)rDrrrrr>rrr4generate_autosummary_contentsn  " &&             r.rstFTutf-8sources output_dirsuffix base_pathbuilderrk overwriteencodingc  s |r tjdtdd|rtjdtddtt|} t| dkr/| dddg| dd} ttd d | |rFttd |durSfd d |D}t |} t |} g} |rd|j j }ni}tt| tdD]}|jdurwqn|ptj|j}t|zt|j\}}}}||dd}Wn@ty}z4zt|j\}}}}||dd}Wntyttd|j|fYWYd}~qnwWYd}~nd}~wwi}|r||j jt|||| |j|||j||| }tj |||||}tj |rNt!|| d }|"}Wdn 1swY||kr(qn|rMt!|d| d }|#|Wdn 1sCwY| $|qnt!|d| d }|#|Wdn 1sfwY| $|qn| rt%| |||||||d dSdS)Nz?builder argument for generate_autosummary_docs() is deprecated.rWrXzDtemplate_dir argument for generate_autosummary_docs() is deprecated. z...iz,[autosummary] generating autosummary for: %sz, zutosummary] writing to %scsg|] }tj|qSr3)rtrru)rfilenamerr3r4rsz-generate_autosummary_docs..)keyrrz%[autosummary] failed to import %r: %s)rw)rrrrrkrrDr)&rZr[rlistsortedrhrinforrurjfind_autosummary_in_filesr)r(rrArrtabspathr!rr>replacerrrrr'rr?r@getisfileopenreadwritergenerate_autosummary_docs)rrrrrrkrrDrrshowed_sourcesr?r new_files filename_mapentryrr>rrrrrqrcontentrf old_contentr3rr4rps                r filenamesc Cs^g}|D](}t|ddd}|}|t||dWdn1s'wYq|S)z^Find out what items are documented in source/*.rst. See `find_autosummary_in_lines`. rignore)rerrorsrN)rr splitlinesextendfind_autosummary_in_lines)r documentedrrlinesr3r3r4rs rrrc Cs|r tjdtddzt|\}}}}t|}t|||dWSty+YgSt yE}zt d||fWYd}~gSd}~wt yTt 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)rrzFailed to import '%s': %sNz_Failed to import '%s'; the module executes module level statement and it might call sys.exit().) rZr[rrpydocgetdocr r rrr\ SystemExit) r>rr real_namerrrrrqr3r3r4find_autosummary_in_docstrings*  rrcCstd}td}td}td}td}td}td} g} d} d } d } |}d}d }|D]}|r||}|rAd } q3||}|r[|d } |rZtjtj|| } q3| |}|rj|d } q3| d rrq3||}|r|d }| dr|d d }|r| |dsd||f}| t || | | q3|r| |drq3d}||}|rd }|d }d} d } d } q3| |}|r|d }| t||dq3||}|r|d}q3q3| S)aFind 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*$FNrTr:~rz%s.%s r rW)recompilematchgrouprtrrudirnamestriprrr=searchr r)rrrautosummary_re automodule_re module_reautosummary_item_rerecursive_arg_retoctree_arg_retemplate_arg_rerr@toctreer?current_modulein_autosummary base_indentremr>r3r3r4r s                   r cCstjdtdtdd}|jddddtd |jd d td d |jddddtdd|jdddddtdd|jdddddtdd|jddd d!d"td#d|S)$Nz#%(prog)s [OPTIONS] ...z:For more information, visit .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 )usageepilog descriptionz --versionversion show_versionz %%(prog)s %s)actiondestr. source_file+z&source files to generate rST files for)nargshelpz-oz --output-dirstorerz directory to place all output in)r0r1r5z-sz--suffixrrz/default suffix for files (default: %(default)s))r0r1defaultr5z-tz --templatesrnz0custom template directory (default: %(default)s)z-iz--imported-members store_truerFz0document imported members (default: %(default)s))argparseArgumentParserr add_argumentr)parserr3r3r4 get_parserSs8     r=rargvcCstjtjdtjtjtddtj gd\}}t |}t |t jt jt|t|}|jrB|jjt|jt|j|jd|j|j|ddS)Nrlocalerr)rrD)rr? setlocaleLC_ALL init_consolertrrurinitr#rsetupr`stdoutrarUr= parse_argsrnr)rvrrrr2rrr)r>r$rrDr6r3r3r4main}s   rG__main__)rc)NN) NrNNNFNTr)Tr<r9rr?rtrrrr`rZgettextrrtypingrrrrrr r r jinja2r jinja2.sandboxr sphinx.localerrrsphinx.applicationrsphinx.buildersr sphinx.configrsphinx.deprecationrrPrsphinx.ext.autodoc.importerrsphinx.ext.autosummaryrrrr sphinx.pycoderrsphinx.registryr sphinx.utilrrrsphinx.util.inspectr sphinx.util.osutilr!sphinx.util.templater" getLoggerr9rr#r=rUrAr^rbrirjrrCrrrrr r:r=r>rGr3r3r3r4s  (              :6  _   _$*