B \NJ@srdZddlmZddlZddlZddlZddlZddlZddlmZddlm Z ddl m Z ddl Z ddl mZmZddlmZdd l mZdd lmZdd lmZmZmZd ejkrejd d Zn dddgZdZeddgZddZddZ d0ddZ!d1ddZ"ddZ#gfdd Z$d2d"d#Z%gfd$d%Z&d&d'Z'd(d)Z(d*d+Z)ej*d,dfd-d.Z+e,d/krne+dS)3u 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-2019 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. )print_functionN)fnmatch)path) binary_type)__display_version__ package_dir) EXTENSIONS)__)rst)FileAvoidWrite ensuredirwalkZSPHINX_APIDOC_OPTIONS,membersz undoc-memberszshow-inheritancez __init__.pyz.pyz.pyxcCs"|r|}|r|d|7}n|}|S)z#Join package and module with a dot..)packagemodulenamerr0lib/python3.7/site-packages/sphinx/ext/apidoc.pymakename8s rc Cst|jd||jf}|jr2ttd|dS|jsTt|rTttd|n.ttd|t |}| |WdQRXdS)z0Write the output file for module/package .z%s.%szWould create file %s.Nz!File %s already exists, skipping.zCreating file %s.) rjoindestdirsuffixdryrunprintr forceisfiler write)rtextoptsfnamefrrr write_fileEs r#TcCs4|rt|}dddg|dt|}d||fS)z2Create a heading of [1, 2 or 3 supported].=-~z%s %s )r escapelen)levelrr(Z underliningrrrformat_headingTs r+cCs,dt||}xtD]}|d|7}qW|S)z4Create the automodule directive and add the options.z.. automodule:: %s z :%s: )rOPTIONS)rrZ directiveZoptionrrrformat_directive]s r-cCs>|jstdd|}nd}|t||7}tt||||dS)z.Build the text of the file and write the file.r'z %s moduleN) noheadingsr+r-r#r)rrr rrrrcreate_module_filefs r0cstd|s dndt||}jr<|s<|t||7}|d7}fdd|D}|r|tdd7}|d 7}x"|D]} |d t||| f7}qrW|d7}fd d|D} | r|tdd 7}jr:|d 7}x| D]\} t|t|| } |d | 7}jstdd| } nd} | tt|| |7} t| | qWnVxT| D]L} t|t|| } jsn|tdd| 7}|tt|| |7}|d7}q@W|d7}js|s|tdd7}|t||7}tt|||dS)z.Build the text of the file and write the file.r'z %s packagez %s namespace cs&g|]}tt|ts|qSr) shall_skiprrINITPY).0sub)excludesr rootrr sz'create_package_file..Z Subpackagesz.. toctree:: z %s.%s cs6g|].}tt|s|tkrt|dqS)r)r2rrr3splitext)r4r5)r6r r7rrr8sZ Submodulesz %s z %s moduler.zModule contentsN)r+r modulefirstr-separatemodulesr/r#)r7Zmaster_packageZsubrootpy_filesr subs is_namespacer6rr5ZsubmodsZsubmodZmodfileZfiletextr)r6r r7rcreate_package_filersL       r@modulescCsttdd|jdd}|d7}|d|j7}|d}x,|D]$}||drPq<|}|d |7}q}t t |||st|d }t|||||qWq`W|S)z` Look for every file in the directory tree and create the corresponding ReST files. followlinksFrPrIN)rRc3s6|].}t|dtkrtt|s|VqdS)r'N)rr: PY_SUFFIXESrOr)r4r")r6r7rr szrecurse_tree..r)r)rrHc3s.|]&}|stt|s|VqdS)N)rErOrr)r4r5)exclude_prefixesr6r7rrrUs r'r)getattrr3rKlistdirsplitrsepr sortedremoveinsertr)r2rlstripreplacer@appendrAssertionErrorr:r0)rootpathr6r rRrPrIZ root_packageZ toplevelsr>filesr=Zis_pkgr?Z subpackageZpy_filerr)rVr6r7r recurse_treesJ      " (   rdcCs 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)r7r6excluderrrrOs  rOc Csjtjdtdtdd}|jddddtd |jd td d |jd dtdd|jdddddtdd|jddddtdtdd|jddd d!td"d#|jd$d%d d&d'td(d)|jd*d+d d,td-d#|jd.d/d d0td1d#|jd2d3d d4td5d#|jd6dd7d8td9d)|jd:d;dd?d d@tdAd#|jdBdCd dDtdEd#|jdFd dGtdHd#|jdIdJddKdLtdMd)|jdNdOd dPtdQd#|jdRdSd dTtdUd#|jdVdWddXtdYd#|jdZd[dd\td]d#|jd^d_ddtd`d#|jdadbddctddd#|tde}x2tD]*}|jdf|dgdh|ditdj|dkq8W|S)lNzH%(prog)s [OPTIONS] -o [EXCLUDE_PATTERN, ...]z5For 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.)ZusageZepilogZ descriptionz --versionversionZ show_versionz %%(prog)s %s)actiondestrf module_pathzpath to module to document)helpexclude_pattern*zGfnmatch-style file and/or directory patterns to exclude from generation)nargsrjz-oz --output-dirZstorerTzdirectory to place all output)rgrhZrequiredrjz-dz --maxdepthrCz;maximum depth of submodules to show in the TOC (default: 4))rgrhtypedefaultrjz-fz--force store_truerzoverwrite existing files)rgrhrjz-lz--follow-linksrRFzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rgrhrprjz-nz --dry-runrz%run the script without creating filesz-ez --separater<z1put documentation for each module on its own pagez-Pz --privaterPzinclude "_private" modulesz --tocfiletocfilerAz0filename of table of contents (default: modules)z-Tz--no-tocZ store_falsez%don't create a table of contents filez-Ez --no-headingsr/zedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstr;z7put module documentation before submodule documentationz--implicit-namespacesrIzNinterpret module paths according to PEP-0420 implicit namespaces specificationz-sz--suffixrr zfile 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--ext-%sZ append_constz sphinx.ext.%s extensionszenable %s extension)rgZconstrhrj)argparseArgumentParserr add_argumentrintZadd_argument_groupr)parsergroupZextrrr get_parser*s                                            r~r'c CsVtjtjdtjtjtddt }| |}t |j }|j dkr`|tjd|_ |jdr||jdd|_t|sttd|tjd td|jst|jd d |jD}t|||}|jrd|j#pHd|j$pZ|j#pZdd|jdddddgddd|j%|d||j&d} |j'r| d(|j't)|j t*r| d+d| d<t)|j"t*r| d+d| d<t)|j#t*r| d+d| d<t)|j$t*r | d+d| d<|jsR|j,| d|j-dn|j.rRt/|||j.d S) z+Parse and check the command line arguments.r.localesphinxNrSrr'z%s is not a directory.)filecSsg|]}t|qSr)rabspath)r4rerrrr8szmain..r) quickstartz %s FrHZAuthorindexTzsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todoZen)rrZdotprojectrurfrvrZmasterZepubrwZmakefileZ batchfileZ make_modeZmastertocmaxdepthZ mastertoctreeZlanguagerirtrwrzutf-8rurfrv)ZsilentZ overwrite)0rr setlocaleLC_ALLZ init_consolerKrrrr~ parse_argsrrirBrYrZrrEisdirrr sysstderrexitrr rrkrdrsZ sphinx.cmdrrDdictrurfrvrCrtrwextend isinstancerdecodeZgeneraterrrrG) argvr|argsrbr6rAZqsrFrrdrrrmains|             r__main__)T)N)rA)-__doc__Z __future__rrxrNrrKrrrZsixrZ sphinx.localerrrZsphinx.cmd.quickstartrr Z sphinx.utilr Zsphinx.util.osutilr r r environrYr,r3setrTrr#r+r-r0r@rGr2rdrOr~rr__name__rrrrsH            <  A YN