o $aK@sdZddlZddlZddlZddlZddlZddlmZddlmZddlm Z ddlm Z ddl m Z m Z mZmZddlZddlmZmZdd lmZdd lmZdd lmZmZdd lmZd ejvrnejd dZngdZdee Z e !eddZ"de#de$fddZ%de#de#fddZ&dHde#dee#de$fddZ'de#de#d e ddfd!d"Z( dId#e#d$e#d e d%e#ddf d&d'Z)gdfd(e#d)e#d*e#d+ee#d e d,ee#d-e$d.ee#d%e#ddfd/d0Z* 1 dJd1ee#d e de#d%e#ddf d2d3Z+gfde#d e d.ee#de$fd4d5Z,de#d e d.ee#de$fd6d7Z-d8e#d.ee#d e de ee#ee#ee#fddffd9d:Z.d8e#d.ee#d e de$fd;d<Z/ dId8e#d.ee#d e d%e#dee#f d=d>Z0d(e#d.ee#de$fd?d@Z1dej2fdAdBZ3ej4dCdfdDee#de5fdEdFZ6e7dGkre6dSdS)Ku sphinx.ext.apidoc ~~~~~~~~~~~~~~~~~ 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/ :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N)copyfnmatch)EXTENSION_SUFFIXES)path)Any GeneratorListTuple)__display_version__ package_dir) EXTENSIONS)__)FileAvoidWrite ensuredir) ReSTRendererSPHINX_APIDOC_OPTIONS,)membersz undoc-memberszshow-inheritance)z.pyz.pyx templatesapidocfilenamereturncCs4t|}tttddD] }|d|krdSq dS)z)Check *filename* is __init__ file or not.T)keyreverse__init__F)rbasenamesorted PY_SUFFIXESlen)rrsuffixr!3/usr/lib/python3/dist-packages/sphinx/ext/apidoc.py is_initpy3s  r#modnamescGsdtd|S)zJoin module names with dots..N)joinfilter)r$r!r!r" module_join=sr(dirnamefilescCs8|dur |dur dS|durt|}tdd|DS)z+Check given *files* contains __init__ file.NFcs|] }t|r|VqdSNr#.0fr!r!r" Iz is_packagedir..)oslistdirany)r)r*r!r!r" is_packagedirBs  r6nametextoptscCst|dd}t|jd||jf}|jr!|sttd|dS|js7t |r7|s5ttd|dSdS|sAttd|t |}| |WddS1sVwYdS)z0Write the output file for module/package .quietNz%s.%szWould create file %s.z!File %s already exists, skipping.zCreating file %s.) getattrrr&destdirr dryrunprintrforceisfilerwrite)r7r8r9r:fnamer0r!r!r" write_fileLs   "rCpackageruser_template_dircCs`tt}|jrd|vr|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_dirrenderrC)rDrr9rEoptionsrIcontextr8r!r!r"create_module_file_s  rSrootmaster_packagesubrootpy_filessubs is_namespaceexcludesc  sfdd|D} fdd|D} fdd| D} tt} jr2d| vr2| dt} | | | |jj| j jd } t |t g d| }t | || rijrk| D] }t d||q_dSdSdS) rFcs,g|]}tt|st|qSr!)is_skipped_packagerr&r()r/pkgnamerZrUr9rTrVr!r" vsz'create_package_file..cs6g|]}tt|st|s|ddqS)r%r)is_skipped_modulerr&r#splitr/sub)rZr9rTr!r"r^zs csg|]}t|qSr!)r()r/modname)rUrVr!r"r^}srG) r\ subpackages submodulesrY modulefirstseparatemodulesrJrHmaxdepthz package.rst_tN)rrKrLrMr(rfrgrNrhrrOrPrCrS)rTrUrVrWr9rXrYrZrErdrerQr\rRr8 submoduler!r]r"create_package_fileqs8     rjmodulescCsp|d}|ddD]}||dr||q |}q |j|j|d}t|tgd|}t|||dS)zCreate the module's index.Nr%)headerrhdocnamesz toc.rst_t) sort startswithremovermrhrrOrPrC)rkr9r7rE prev_modulemodulerRr8r!r!r"create_modules_toc_files rtcs`tsdSttd}tdd|D}|s |js dStfdd|Dr.dSdS)%Check if we want to skip this module.Fz*.pycsr+r,r-r.r!r!r"r1r2z%is_skipped_package..Tc3s"|] }tt|VqdSr,) is_excludedrr&r.r)rZr!r"r1s )risdirglobr&r5implicit_namespacesall)r)r9rZr*regular_packager!rwr"r[s  r[cCs,t|sdSt|dr|jsdSdS)ruT_F)rexistsrrprL)rr9rZr!r!r"r_s r_rootpathc#st|dd}t|dd}tj||dD]/\}}tfdd|D}|r*dndtfd d|D|d d <||fVqd S) z@Walk through the directory and list files and subdirectories up. followlinksFrL)rc3s0|]}|trtt|s|VqdSr,)endswithrrvrr&r.)rZrTr!r"r1s zwalk..)r%)r%r}c3s0|]}|stt|s|VqdSr,)rprvrr&raexclude_prefixesrZrTr!r"r1sN)r;r3walkr)rrZr9rrLrXr*r!rr"rs  "rcCs&t|||D] \}}}|rdSqdS)zACheck the given directory contains child module/s (at least one).TF)r)rrZr9rTrXr*r!r!r"has_child_modules rc Cst|dd}t|s |r|tjd}nd}g}t|||D]\}}} td| } | o-|} | rI| ddD]} t| rG| | | d| q6n ||krU|sU|dd=q| sY| r|sft | dksft ||s|t |d tj tjd} | rt |||rt||| | ||| || |t|| q||kr|dusJ| D]}tt||||s|dd}t||||||qq|S)z` Look for every file in the directory tree and create the corresponding ReST files. rzFNrr%)r;r6r`rseprr#rqinsertrr[lstripreplacerrjrMr(r_r&rS)rrZr9rErz root_package toplevelsrTrXr*is_pkgrYr0 subpackagepy_filersr!r!r" recurse_treesP          rcCs|D] }t||r dSqdS)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". TFr)rTrZexcluder!r!r"rv#s  rvc 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|dsq2|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 --versionversion 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_truer:z,no output on stdout, just warnings on stderr)rrrz-dz --maxdepthrhz;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcer?zoverwrite existing filesz-lz--follow-linksrFzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rrrrz-nz --dry-runr=z%run the script without creating filesz-ez --separatergz1put documentation for each module on its own pagez-Pz --privaterLzinclude "_private" modulesz --tocfiletocfilerkz0filename of table of contents (default: modules)z-Tz--no-toc store_falsez%don't create a table of contents filez-Ez --no-headingsrNzedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrfz7put module documentation before submodule documentationz--implicit-namespacesrzzNinterpret module paths according to PEP-0420 implicit namespaces specificationz-sz--suffixr rstzfile 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-projectrmz(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 extensionsrMzenable arbitrary extensions)metavarrrrz--ext-%s append_constz sphinx.ext.%szenable %s extension)rconstrrzProject templatingz-tz --templatedir TEMPLATEDIR templatedirz%template directory for template files)rrr)argparseArgumentParserr add_argumentr intadd_argument_groupr )parsergroupextr!r!r" get_parser/s                         rrargvc Cshtjtjdtjtjtddt }| |}t |j }|j dur0|tjd|_ |jdr>|jdd|_t|sSttd|tjd td|js[t|jd d |jD}t||||j}|jr%d d lm }|!d}d}|D]} | |drq| }|d| 7}qid|jddddd|j d|j"pdd|j#pdd|j$p|j#pddd|jdddddgdd dd!dd"dd#|j%d$|d%d&||j&d'} |j'r| d(|j'|j)rd| d(<| dddD]} d)| vr| d*| | d(| d)q|js#|j+| d|j,|jd*d S|j-r2t.|||j-|jd S)+z+Parse and check the command line arguments.rllocalesphinxNrr%rz%s is not a directory.)filecSsg|]}t|qSr!)rabspath)r/rr!r!r"r^szmain..r) quickstartz %s rrFdotr}projectrAuthorrrr masterindexepubTr)zsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todomakefile batchfile make_modemastertocmaxdepth mastertoctreelanguageen)rrr:r)silent overwriter)/rr setlocaleLC_ALL init_consoler3rr&r r parse_argsrrrmr`rr rprxr>rsysstderrexitr=rr<rrrr sphinx.cmdrrorrrrhrrextendr:rqgenerater?rrt) rrargsrrZrkqsrrr8rsdrr!r!r"mains                 r__main__)NNr,)rkN)8__doc__rryrr3rrrimportlib.machineryrrtypingrrr r sphinx.localerr r sphinx.cmd.quickstartr rsphinx.util.osutilrrsphinx.util.templaterenvironr`rKtuplerr&rOstrboolr#r(r6rCrSrjrtr[r_rrrrvrrrrr__name__r!r!r!r"s             & "    6 $a L