U \ShJ @s`dZddlmZddlZddlZddlZddlZddlZddlmZddl m Z ddl m Z ddlm Z ddl mZmZddlZdd lmZmZdd lmZdd lmZdd lmZmZdd lmZdejkrejddZn dddgZdee Z e !eddZ"dddddZ#dddddZ$dOdddd d!d"Z%ddd#d$d%d&d'Z&dPddd#dd$d(d)d*Z'gdfdddd+d#d+dd+dd$d, d-d.Z(dQd+d#ddd$d0d1d2Z)gfdd#d+dd3d4d5Z*dd#d+dd6d7d8Z+dd+d#d9d:d;d<Z,dd+d#dd:d=d>Z-dRdd+d#dd+d?d@dAZ.dd+ddBdCdDZ/dEdFdGdHZ0ej1dIdfd+dJdKdLdMZ2e3dNkr\e2dS)SuCreates 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/ ) annotationsN)copyfnmatch)EXTENSION_SUFFIXES)path)Any Generator)__display_version__ package_dir) EXTENSIONS)__)FileAvoidWrite ensuredir) ReSTRendererZSPHINX_APIDOC_OPTIONS,membersz undoc-memberszshow-inheritance)z.pyz.pyxZ templatesZapidocstrbool)filenamereturncs*t|tfddtttddDS)z)Check *filename* is __init__ file or not.c3s|]}d|kVqdS)__init__N).0suffixbasenamerD/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/ext/apidoc.py 3szis_initpy..T)keyreverse)rranysorted PY_SUFFIXESlen)rrrr is_initpy0s   r%)modnamesrcGsdtd|S)zJoin module names with dots..N)joinfilter)r&rrr module_join9sr*z str | Nonezlist[str] | None)dirnamefilesrcCs8|dkr|dkrdS|dkr&t|}tdd|DS)z+Check given *files* contains __init__ file.NFcss|]}t|r|VqdSNr%rfrrrrEsz is_packagedir..)oslistdirr!)r+r,rrr is_packagedir>s  r3rNone)nametextoptsrc Cst|dd}t|j|d|j}|jrD|s@ttd|dS|jsjt |rj|sttd|n2|s~ttd|t |}| |W5QRXdS)z0Write the output file for module/package .quietNr'zWould create file %s.z!File %s already exists, skipping.zCreating file %s.) getattrrr(destdirrdryrunprintr forceisfilerwrite)r5r6r7r8fnamer0rrr write_fileHs  rA)packagerr7user_template_dirrcCs`tt}|jr d|kr |dt||}|j |||d}t|tgd|}t |||dS).Build the text of the file and write the file.private-members) show_headingsrqualnameautomodule_optionsz module.rst_tN) rOPTIONSincludeprivateappendr* noheadingsr template_dirrenderrA)rBrr7rCoptionsrGcontextr6rrrcreate_module_file[s  rQz list[str]) rootmaster_packagesubrootpy_filesr7subs is_namespaceexcludesrCrc  sfdd|D} fdd|D} tt| } fdd| D} tt} jrpd| krp| dt} | | | |jj| j j d } t |t g d| }t| || rވjr| D]}td||qdS) rDcs,g|]$}tt|st|qSr)is_skipped_packagerr(r*)rpkgnamerXrSr7rRrTrr ssz'create_package_file..cs6g|].}tt|st|s|ddqS)r'r)is_skipped_modulerr(r%splitrsub)rXr7rRrrr\wscsg|]}t|qSr)r*)rmodname)rSrTrrr\{srE) rZ subpackages submodulesrW modulefirstseparatemodulesrHrFmaxdepthz package.rst_tN)r"setrrIrJrKr*rdrerLrfrrMrNrArQ)rRrSrTrUr7rVrWrXrCrbrcrOrZrPr6 submodulerr[rcreate_package_filems6       rimodules)rjr7r5rCrcCsp|d}|ddD]"}||dr6||q|}q|j|j|d}t|tgd|}t|||dS)zCreate the module's index.Nr')headerrfZdocnamesz toc.rst_t) sort startswithremoverlrfrrMrNrA)rjr7r5rC prev_modulemodulerPr6rrrcreate_modules_toc_files rr)r+r7rXrcsXtsdSttd}tdd|D}|s@|js@dStfdd|DS)%Check if we want to skip this module.Fz*.pycss|]}t|r|VqdSr-r.r/rrrrsz%is_skipped_package..Tc3s |]}tt|VqdSr-) is_excludedrr(r/r+rXrrrs)risdirglobr(r!implicit_namespacesall)r+r7rXr,Zregular_packagerrurrYs  rY)rr7rXrcCs,t|sdSt|dr(|js(dSdS)rsT_F)rexistsrrnrJ)rr7rXrrrr]s  r]z7Generator[tuple[str, list[str], list[str]], None, None])rootpathrXr7rc#st|dd}t|dd}tj||dD]^\}}tfdd|D}|rRdndtfd d|D|d d <||fVq&d S) z@Walk through the directory and list files and subdirectories up. followlinksFrJ)r}c3s.|]&}|trtt|s|VqdSr-)endswithr#rtrr(r/)rXrRrrrs zwalk..)r')r'rzc3s.|]&}|stt|s|VqdSr-)rnrtrr(r_Zexclude_prefixesrXrRrrrs N)r9r1walkr")r|rXr7r}rJrVr,rrrrs  "rcCstddt|||DS)zACheck the given directory contains child module/s (at least one).css|]\}}}|VqdSr-r)r_root_subsr,rrrrsz#has_child_module..)r!r)r|rXr7rrrhas_child_modules r)r|rXr7rCrc Cst|dd}t|s|r*|tjd}nd}g}t|||D]V\}}} td| } | o\|} | r| ddD]"} t| rn| | | d| qnn||kr|s|dd=q>| s| r2|st | dkst ||s|t |d tj tjd} | rt |||rt||| | ||| || |t|| q>||ks@t|dksNt| D]B}tt||||sR|dd}t||||||qRq>|S)z` Look for every file in the directory tree and create the corresponding ReST files. rxFNrr')r9r3r^rseprr%roinsertr$rYlstripreplacerrirKr*AssertionErrorr]r(rQ)r|rXr7rCrxZ root_packageZ toplevelsrRrVr,Zis_pkgrWr0Z subpackageZpy_filerqrrr recurse_treesR       r)rRrXrcstfdd|DS)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". c3s|]}t|VqdSr-rrexcluderRrrr"szis_excluded..)r!)rRrXrrrrts rtzargparse.ArgumentParser)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}|jdidjdkdltdmdntD]*}|jdo|dpdq|dktdr|dsqd|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-dirstorer:Tzdirectory to place all output)rrrequiredrz-q store_truer8z,no output on stdout, just warnings on stderr)rrrz-dz --maxdepthrfz;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcer=zoverwrite existing filesz-lz--follow-linksr}FzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rrrrz-nz --dry-runr;z%run the script without creating filesz-ez --separaterez1put documentation for each module on its own pagez-Pz --privaterJzinclude "_private" modulesz --tocfiletocfilerjz0filename of table of contents (default: modules)z-Tz--no-toc store_falsez%don't create a table of contents filez-Ez --no-headingsrLzedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrdz7put module documentation before submodule documentationz--implicit-namespacesrxzNinterpret 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-projectrlz(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 extensionsrKzenable 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                        rrr)argvrc Csttjdtjt}||}t|j }|j dkrP| tj d|_ |j drl|j dd|_ t|sttd|tjdtd|jst|jdd |jD}t||||j}|jrd d lm}|d}d}|D]&} | |drq| }|d | 7}q|jd d|j |jp*d|j p4d|j!pF|j pFdd|j dddddgddd|j"|d||j#d} |j$r| d%|j$|j&rd| d<| dddD]2} d| kr| d'| | d%| dq|js|j(| d|j)|jdn|j*rt+|||j*|jd S)z+Parse and check the command line arguments.rkNrr'rz%s is not a directory.)filecSsg|]}t|qSr)rabspathrrrrr\szmain..r) quickstartz %s FrzAuthorindexTzsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todoen)rrdotprojectrrrrZmasterZepubrmakefileZ batchfileZ make_modeZmastertocmaxdepthZ mastertoctreelanguagerrrr8r)Zsilent overwriter),locale setlocaleLC_ALLsphinxZ init_consoler parse_argsrrrrlr^rrrnrvr<r sysstderr SystemExitr;rr:rrrrZ sphinx.cmdrrmrrrrfrrextendr8rogenerater=rrr) rrargsr|rXrjqsrpr6rqdrrrrmains~            r__main__)NN)N)rjN)N)4__doc__ __future__rrrwrr1rrrZimportlib.machineryrrtypingrr Z sphinx.localerr r Zsphinx.cmd.quickstartr r Zsphinx.util.osutilrrZsphinx.util.templaterenvironr^rItupler#r(rMr%r*r3rArQrirrrYr]rrrrtrrr__name__rrrrs`            "(  7 aL