B dK @sdZddlZddlZddlZddlZddlZddlmZddlmZddlm Z ddlm Z ddl m Z m Z mZmZmZddlZddlmZmZdd lmZdd lmZdd lmZmZdd lmZd ejkrejd dZn dddgZde e Z!e "eddZ#e$e%dddZ&e$e$dddZ'dDee$eee$e%dddZ(e$e$e dddd Z)dEe$e$e ee$dd!d"d#Z*gdfe$e$e$ee$e ee$e%ee$ee$dd$ d%d&Z+dFee$e e$ee$dd(d)d*Z,gfe$e ee$e%d+d,d-Z-e$e ee$e%d.d/d0Z.e$ee$e e ee$ee$ee$fddfd1d2d3Z/e$ee$e e%d1d4d5Z0dGe$ee$e ee$ee$d6d7d8Z1e$ee$e%d9d:d;Z2ej3d<d=d>Z4ej5d?dfee$e6d@dAdBZ7e8dCkre7dS)HuCreates reST files corresponding to Python modules for code documentation. Parses a directory tree looking for Python modules and packages and creates ReST files appropriately to create code documentation with Sphinx. It also creates a modules index (named modules.). This is derived from the "sphinx-autopackage" script, which is: Copyright 2008 Société des arts technologiques (SAT), https://sat.qc.ca/ N)copy)fnmatch)EXTENSION_SUFFIXES)path)Any GeneratorListOptionalTuple)__display_version__ package_dir) EXTENSIONS)__)FileAvoidWrite ensuredir) ReSTRendererZSPHINX_APIDOC_OPTIONS,membersz undoc-memberszshow-inheritance)z.pyz.pyxZ templatesZapidoc)filenamereturncCs:t|}x*tttddD]}|d|krdSqWdSdS)z)Check *filename* is __init__ file or not.T)keyreverse__init__FN)rbasenamesorted PY_SUFFIXESlen)rrsuffixr^/work/yifan.wang/ringdown/master-ringdown-env/lib/python3.7/site-packages/sphinx/ext/apidoc.py is_initpy.s   r )modnamesrcGsdtd|S)zJoin module names with dots..N)joinfilter)r!rrr module_join8sr%)dirnamefilesrcCs8|dkr|dkrdS|dkr&t|}tdd|DS)z+Check given *files* contains __init__ file.NFcss|]}t|r|VqdS)N)r ).0frrr Dsz is_packagedir..)oslistdirany)r&r'rrr is_packagedir=s  r.)nametextoptsrc Cst|dd}t|jd||jf}|jrB|s>ttd|dS|jsht |rh|sttd|n2|s|ttd|t |}| |WdQRXdS)z0Write the output file for module/package .quietNz%s.%szWould create file %s.z!File %s already exists, skipping.zCreating file %s.) getattrrr#destdirrdryrunprintrforceisfilerwrite)r/r0r1r2fnamer)rrr write_fileGs  r;)packagerr1user_template_dirrcCs`tt}|jr d|kr |dt||}|j |||d}t|tgd|}t |||dS)z.Build the text of the file and write the file.zprivate-members) show_headingsrqualnameautomodule_optionsz module.rst_tN) rOPTIONSincludeprivateappendr% noheadingsr template_dirrenderr;)r<rr1r=optionsr?contextr0rrrcreate_module_fileZs  rI) rootmaster_packagesubrootpy_filesr1subs is_namespaceexcludesr=rc  sfdd|D} fdd|D} tt| } fdd| D} tt} jrpd| krp| dt} | | | |jj| j j d } t |t g d| }t| || rjrx| D]}td||qWdS) z.Build the text of the file and write the file.cs,g|]$}tt|st|qSr)is_skipped_packagerr#r%)r(pkgname)rPrKr1rJrLrr rsz'create_package_file..cs6g|].}tt|st|s|ddqS)r"r)is_skipped_modulerr#r split)r(sub)rPr1rJrrrSvscsg|]}t|qSr)r%)r(modname)rKrLrrrSzszprivate-members) rR subpackages submodulesrO modulefirstseparatemodulesr@r>maxdepthz package.rst_tN)rsetrrArBrCr%rZr[rDr\rrErFr;rI)rJrKrLrMr1rNrOrPr=rXrYrGrRrHr0 submoduler)rPrKr1rJrLrcreate_package_filels0        r_modules)r`r1r/r=rcCst|d}x2|ddD]"}||dr8||q|}qW|j|j|d}t|tgd|}t|||dS)zCreate the module's index.Nr")headerr\Zdocnamesz toc.rst_t) sort startswithremoverbr\rrErFr;)r`r1r/r= prev_modulemodulerHr0rrrcreate_modules_toc_files rh)r&r1rPrcsdtsdSttd}tdd|D}|s@|js@dStfdd|Dr\dSdSdS)z%Check if we want to skip this module.Fz*.pycss|]}t|r|VqdS)N)r )r(r)rrrr*sz%is_skipped_package..Tc3s |]}tt|VqdS)N) is_excludedrr#)r(r))r&rPrrr*sN)risdirglobr#r-implicit_namespacesall)r&r1rPr'Zregular_packager)r&rPrrQs  rQ)rr1rPrcCs0t|sdSt|dr(|js(dSdSdS)z%Check if we want to skip this module.T_FN)rexistsrrdrB)rr1rPrrrrTs  rT)rootpathrPr1rc#st|dd}t|dd}xptj||dD]^\}}tfdd|D}|rTdndtfd d|D|d d <||fVq(Wd S) z@Walk through the directory and list files and subdirectories up. followlinksFrB)rqc3s.|]&}|trtt|s|VqdS)N)endswithrrirr#)r(r))rPrJrrr*s zwalk..)r")r"rnc3s.|]&}|stt|s|VqdS)N)rdrirr#)r(rV)exclude_prefixesrPrJrrr*s N)r3r+walkr)rprPr1rqrBrNr'r)rsrPrJrrts  "rtcCs(x"t|||D]\}}}|rdSqWdS)zACheck the given directory contains child module/s (at least one).TF)rt)rprPr1_root_subsr'rrrhas_child_modulesrw)rprPr1r=rc Cst|dd}t|s|r*|tjd}nd}g}xlt|||D]Z\}}} td| } | o`|} | rxL| ddD]"} t| rt| | | d| qtWn||kr|s|dd=qB| s| r:|st | dkst ||s|t |d tj tjd} | rt |||rt||| | ||| || |t|| qB||krN|dksRtxJ| D]B}tt||||sX|dd}t||||||qXWqBW|S)z` Look for every file in the directory tree and create the corresponding ReST files. rlFNrr")r3r.rUrseprtr reinsertrrQlstripreplacerwr_rCr%AssertionErrorrTr#rI)rprPr1r=rlZ root_packageZ toplevelsrJrNr'Zis_pkgrOr)Z subpackageZpy_filergrrr recurse_treesB          r)rJrPrcCs x|D]}t||rdSqWdS)zCheck if the directory is in the exclude list. Note: by having trailing slashes, we avoid common prefix issues, like e.g. an exclude "foo" also accidentally excluding "foobar". TF)r)rJrPexcluderrrri s  ri)rc Cstjdtdtdd}|jddddtd |jd td d |jd dtdd|jdddddtdd|jdddtdd|jddddtd td!d"|jd#d$dd%td&d|jd'd(dd)d*td+d,|jd-d.dd/td0d|jd1d2dd3td4d|jd5d6dd7td8d|jd9dd:d;td<d,|jd=d>d?d:td@d|jdAdBddCtdDd|jdEdFddGtdHd|jdIddJtdKd|jdLdMddNdOtdPd,|jdQdRddStdTd|jdUdVddWtdXd|jdYdZdd[td\d|jd]d^dd_td`d|jdadbddtdcd|jdddeddftdgd|tdh}|jdidjdkdltdmdnx2tD]*}|jdo|dpdq|dktdr|dsqfW|tdt}|jdudvdwdxtdydz|S){NzH%(prog)s [OPTIONS] -o [EXCLUDE_PATTERN, ...]z:For more information, visit .aE Look recursively in for Python modules and packages and create one reST file with automodule directives per package in the . The s can be file and/or directory patterns that will be excluded from generation. Note: By default this script will not overwrite already created files.)usageepilog descriptionz --versionversionZ show_versionz %%(prog)s %s)actiondestr module_pathzpath to module to document)helpexclude_pattern*zGfnmatch-style file and/or directory patterns to exclude from generation)nargsrz-oz --output-dirstorer4Tzdirectory to place all output)rrrequiredrz-q store_truer2z,no output on stdout, just warnings on stderr)rrrz-dz --maxdepthr\z;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcer7zoverwrite existing filesz-lz--follow-linksrqFzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rrrrz-nz --dry-runr5z%run the script without creating filesz-ez --separater[z1put documentation for each module on its own pagez-Pz --privaterBzinclude "_private" modulesz --tocfiletocfiler`z0filename of table of contents (default: modules)z-Tz--no-toc store_falsez%don't create a table of contents filez-Ez --no-headingsrDzedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrZz7put module documentation before submodule documentationz--implicit-namespacesrlzNinterpret module paths according to PEP-0420 implicit namespaces specificationz-sz--suffixrrstzfile suffix (default: rst)z-Fz--fullfullz.generate a full project with sphinx-quickstartz-az--append-syspathappend_syspathz9append module_path to sys.path, used when --full is givenz-Hz --doc-projectrbz(project name (default: root module name)z-Az --doc-authorauthorz,project author(s), used when --full is givenz-Vz --doc-versionz*project version, used when --full is givenz-Rz --doc-releasereleasezEproject release, used when --full is given, defaults to --doc-versionzextension optionsz --extensionsr extensionsrCzenable arbitrary extensions)metavarrrrz--ext-%s append_constz sphinx.ext.%szenable %s extension)rconstrrzProject templatingz-tz --templatedirZ TEMPLATEDIR templatedirz%template directory for template files)rrr)argparseArgumentParserr add_argumentr intadd_argument_groupr )parsergroupextrrr get_parser,s                                                 rry)argvrc Cs<tjtjdtjtjtddt }| |}t |j }|j dkr`|tjd|_ |jdr||jdd|_t|sttd|tjd td|jst|jd d |jD}t||||j}|jrd d lm }|!d}d}x2|D]*} | |drq| }|d| 7}qW|jdd|j |j"pDd|j#pNd|j$p`|j#p`dd|jdddddgddd|j%|d||j&d} |j'r| d(|j'|j)rd| d<xF| dddD]2} d| kr| d*| | d(| dqW|js8|j+| d|j,|jdn|j-r8t.|||j-|jd S)z+Parse and check the command line arguments.ralocalesphinxNrxr"ryz%s is not a directory.)filecSsg|]}t|qSr)rabspath)r(rrrrrSszmain..r) quickstartz %s FrnAuthorindexTzsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todoen)rrzdotprojectrrrrZmasterZepubrmakefileZ batchfileZ make_modeZmastertocmaxdepthZ mastertoctreelanguagerrrr2r)Zsilent overwriter)/rr setlocaleLC_ALLZ init_consoler+rr#r r parse_argsrrrbrUrzrrdrjr6rsysstderrexitr5rr4rrrrZ sphinx.cmdrrcrrrr\rrextendr2regenerater7rrh) rrargsrprPr`qsrfr0rgdrrrrmainsx               r__main__)NN)N)r`N)N)9__doc__rrkrr+rrrZimportlib.machineryrrtypingrrrr r Z sphinx.localerr r Zsphinx.cmd.quickstartr rZsphinx.util.osutilrrZsphinx.util.templaterenvironrUrAtuplerr#rEstrboolr r%r.r;rIr_rhrQrTrtrwrrirrrrr__name__rrrr sV           (%  * $5 a"L