U \Shdf@sdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddlm Z ddl m Z mZmZmZddlmZddlmZddlZddlmZmZdd lmZdd lmZdd lmZdd lm Z dd l!m"Z"ddl#m$Z$m%Z%m&Z&m'Z'ddlm(Z(ddl)m*Z*m+Z+ddl,m-Z-ddl.m/Z/m0Z0m1Z1ddl2m3Z3m4Z4ddl5m6Z6ddl7m8Z8e rnddl9m:Z:e/;e<Z=GdddZ>GdddeZ?dddddZ@dOd!d!d!d"d#d$ZAGd%d&d&ZBGd'd(d(ZCdd)d*d+d,d-ZDdPd!ddd&d!d.dd.d/d0d0d!d1 d2d3ZEdQd8d0d!d0d.dd.d!dd9 d:d;ZFd8dd?ZGdRd!d0dr1r1r2rhszAutosummaryRenderer.renderN)r7r8r9r:r3rhr1r1r1r2rWrsrWc@sTeZdZddddddZdddddd Zdddd d d d Zd ddddZdS) ModuleScannerrr")rBobjr$cCs||_||_dSr5)rBobject)r0rBrjr1r1r2r3szModuleScanner.__init__r<)r=valuer$cCst|j||jjSr5)rrBrkrM)r0r=rlr1r1r2get_object_typeszModuleScanner.get_object_typer/)r=rlrMr$c Cs\z|jd|||diWStk rV}z tjtd||ddWYdSd}~XYnXdSNzautodoc-skip-memberFz\autosummary: failed to determine %r to be documented, the following exception was raised: %srY)type)rBr6 Exceptionloggerwarningr)r0r=rlrMexcr1r1r2 is_skippeds  zModuleScanner.is_skipped list[str])imported_membersr$c Cs,g}zt|jj}|}Wntk r6i}YnXt|j|jjD]}zt |j|}Wnt k rtd}YnX| ||}| |||rqHzBd|f|krd}n,t |rd}nt |d|jjkrd}nd}Wnt k rd}YnX|jjj } |s|dks| rHdt|jkrH||qH|S)NFTr8__all__)r for_modulerkr7find_attr_docsr members_ofrBr*rAttributeErrorrmrtinspectismoduler(dirappend) r0rvmembersanalyzer attr_docsr=rlrMimportedrespect_module_allr1r1r2scansF          zModuleScanner.scanN)r7r8r9r3rmrtrr1r1r1r2ris rir Sequence[str])rjconfr$cCs"|jrt|St|pt|SdS)zGet the members of ``obj``, possibly ignoring the ``__all__`` module attribute Follows the ``conf.autosummary_ignore_module_all`` setting.N)r(rr)rjrr1r1r2r{sr{r/rez str | None) r=rjparentr>rfrvrBr?rgmodnamequalnamer$c spt||dddddfdd dddfd d dddfd d dddfd d gdfddddddfdd } dddfdd } dGdddddfdd } i}||jdkrDt|}|||d<jj }|pd t|ko|}| |d!h|d"\|d#<|d$<| |d%h|d"\|d&<|d'<| |d(h|d"\|d)<|d*<| |d\|d+<|d,<t|d-}|r|r|d$|d'|d*|d,}|r d t|kr | |dhdd"\}}||7}fd.d/|D}fd0d/|D}t |}ngg}}d}| |||d1\}}|||d2<|||d3<nljd%krt||d<t t|t |j |d4<| |d5hd6g\|d7<|d8<| |d9d:h\|d+<|d,<| dksĈdkrt \} jd;krd|d%<jd?kr}nd.skip_memberzdict[str, Any])rjr$cs&tjj|gt}dd|DS)NcSsi|]\}}||jqSr1)rk).0r=memberr1r1r2 szKgenerate_autosummary_content..get_class_members..)sphinxrXZautodocget_class_membersritems)rjr)rr1r2rsz7generate_autosummary_content..get_class_membersc sFi}t|jD]0}zt||||<Wqtk r>YqYqXq|Sr5)r{r*rr|)rjrr=rr1r2get_module_memberss z8generate_autosummary_content..get_module_memberscs(jdkr|Sjdkr$|SiS)Nmoduleclass)rM)rj)docrrr1r2get_all_memberss   z5generate_autosummary_content..get_all_membersTzset[str]ruztuple[list[str], list[str]])rjtypesinclude_publicrr$c sg}g}|}|D]\}}t||} | j|kr|sLt|dd|jkr||| j} | dkrdq| dkr||||q||||ks|ds||q||fS)Nr8TF_)rrrMgetattrr7r startswith) rjrrrrpublicZ all_membersr=rlrNZskipped)rBrrr1r2 get_memberss"      z1generate_autosummary_content..get_members)rr$cszgg}}zRt}|}|D]6\}}|dkr"||kr"|||ds"||q"Wntk rpYnX||fS)z'Find module attributes with docstrings.rwr)rryrzrrr)rattrsrrr namespace attr_namer=r1r2get_module_attrs s     z6generate_autosummary_content..get_module_attrsrzSequence[str] | None)rjskippublic_membersr$c sg}g}t|jD]\}}}||kr(qd|}zt|} | rPt| drPWqWntk rfYnX|||dk r||kr||q|ds||q||fS)N.Z__sphinx_mock__r)pkgutil iter_modules__path__rhasattr ImportErrorrr) rjrrrrrrZ_ispkgfullnamerrr1r2 get_modules/s&     z1generate_autosummary_content..get_modulesrrrxfunction)rZ functionsZ all_functionsrclassesZ all_classes exception exceptionsZall_exceptions attributesZall_attributesrcsg|]}d|qSrr1rrrr1r2 rsz0generate_autosummary_content..csg|]}d|qSrr1rrr1r2rts)rrmodules all_modulesZinherited_membersmethodr3methodsZ all_methods attributeproperty)rrrrr)rrZobjnamer=rMrPr^)N)rupdaterMrirr*r(rrrset__dict__keysrrsplitrUrh)r=rjrr>rfrvrBr?rgrrrrrnsscannerr ispackagerZimported_modulesZall_imported_modulesrrr shortnamer1)rBrrrrr=rrr2generate_autosummary_contents                       r.rstFTutf-8ru) sources output_dirsuffix base_pathrvrB overwriteencodingr$cst|}t|dkr2|dddg|dd}ttdd||r`ttd|dk rzfdd |D}t|} t|} g} |r|jj } ni} tt | t d D]} | j dkrq|pt j | j }t|z&t| j\}}}}||d d }Wntk r}zz&t| j\}}}}||d d }Wntk r}zb|jrh|j|jg}n |j|g}td d|D}ttd| jd|WY WYqW5d}~XYnXW5d}~XYnXi}|r||jjt|||| | j||| j||| }t j || |||}t j |rt!||d}|"}W5QRX||kr^q|rt!|d|d}|#|W5QRX| $|qt!|d|d}|#|W5QRX| $|q| rt%| |||||ddS)N z...iz,[autosummary] generating autosummary for: %sz, zutosummary] writing to %scsg|]}tj|qSr1)r`rra)rfilenamerr1r2rsz-generate_autosummary_docs..)keyrrwcSs"h|]}dt|jd|qSz* z: ror7rr]r1r1r2 sz,generate_autosummary_docs..z5[autosummary] failed to import %s. Possible hints: %srS)rw)rrrrvrBr)&sortedrUrqinforrarWfind_autosummary_in_filesr*r'rr<rr`abspathrrr=replacerrr __cause__rlistrrrr&rr>r?getisfileopenreadwritergenerate_autosummary_docs)rrrrrvrBrrZshowed_sourcesr>rZ new_filesZ filename_mapentryrr=rjrrrrsZexc2rerrorsrgcontentrfZ old_contentr1rr2rs      2   rzlist[AutosummaryEntry]) filenamesr$c CsJg}|D]<}t|ddd$}|}|t||dW5QRXq|S)z^Find out what items are documented in source/*.rst. See `find_autosummary_in_lines`. rignore)rrr)rr splitlinesextendfind_autosummary_in_lines)r documentedrrlinesr1r1r2rs  r)r=rr$c Csz.t|\}}}}t|}t|||dWStk rBYnjtk r}z.ddd|jD}t d|d|W5d}~XYn t k rt d|YnXgS) znFind out what items are documented in the given object's docstring. See `find_autosummary_in_lines`. )rrrScSs"h|]}dt|jd|qSrrrr1r1r2rsz0find_autosummary_in_docstring..zFailed to import z. Possible hints: Nz_Failed to import '%s'; the module executes module level statement and it might call sys.exit().) rpydocgetdocrrr|rrarprint SystemExit) r=rZ real_namerjrrrrsrr1r1r2find_autosummary_in_docstrings$ r)rrrr$cCstd}td}td}td}td}td}td} g} d} d } d } |}d}d }|D]}|rv||}|rd } qf||}|r|d } |rftjtj|| } qf| |}|r|d } qf| d rqf||}|rX|d }| dr|d d }|rB| |dsB|d|}| t || | | qf|rf| |drrqfd}||}|rd }|d }d} d } d } qf| |}|r|d }| t||dqf||}|rf|d}qfqf| 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*$FNrwTr:~r r)recompilematchgroupr`rradirnamestriprrr;searchrr)rrrZautosummary_reZ automodule_reZ module_reZautosummary_item_reZrecursive_arg_reZtoctree_arg_reZtemplate_arg_rerr?Ztoctreer>Zcurrent_moduleZin_autosummary base_indentrRmr=r1r1r2rs                   rzargparse.ArgumentParser)r$cCstjdtdtdd}|jddddtd |jd d td d |jddddtdd|jdddddtdd|jdddddtdd|jddd d!d"td#d|jd$d%d 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 --versionversionZ 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)r r rz-sz--suffixrrz/default suffix for files (default: %(default)s))r r defaultrz-tz --templatesrZz0custom template directory (default: %(default)s)z-iz--imported-members store_truervFz0document imported members (default: %(default)s)z-az--respect-module-allrzPdocument exactly the members in module __all__ attribute. (default: %(default)s))argparseArgumentParserr add_argumentr )parserr1r1r2 get_parser~sD      rr)argvr$cCsttjdtjttj}t|t j t j t |t |}|jrh|jjt|j|j |j_t|j|jd|j|j|ddS)Nrwr)rvrB)locale setlocaleLC_ALLrZ init_consoler!Zget_translatorrsetupsysstdoutstderrrOr parse_argsrZr*rbrrrrr(rr rrrv)rrBr4r1r1r2mains    r!__main__)rP)NN)NrNFNTr)N)NN)Mr: __future__rrr}rr`rrrrrtypingrrrrZjinja2rZjinja2.sandboxr Z sphinx.localerr r Zsphinx.applicationr Zsphinx.buildersr Z sphinx.configrrLrZsphinx.ext.autodoc.importerrZsphinx.ext.autosummaryrrrrrZ sphinx.pycoderrZsphinx.registryrZ sphinx.utilrrrZsphinx.util.inspectrrZsphinx.util.osutilrZsphinx.util.templatergettextr getLoggerr7rqr!r;rOrVrWrir{rrrrrrrr!r1r1r1r2sx               &>&? \`.