o NiV@s,dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z ddlm Z ddlmZddlmZmZmZddlZdd lmZmZdd lmZdd lmZdd lmZdd lmZmZddl m!Z!er|ddl"m#Z#m$Z$e%e&Z'dej(vrej(d)dZ*ngdZ*ddge+e RZ,e -eddZ.d^ddZ/d_d d!Z0d`dad%d&Z1dbd,d-Z2 dcddd1d2Z3 3 dedfd>d?Z4 @ dgdhdAdBZ5 3didjdCdDZ6dkdFdGZ7dldJdKZ8dmdLdMZ9 dcdndOdPZ:dodQdRZ;dpdTdUZe&d\kre?e>e j@d]ddS)ruCreates 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)copy)EXTENSION_SUFFIXES)path)Path) TYPE_CHECKINGAnyProtocol)__display_version__ package_dir) EXTENSIONS)__)logging)FileAvoidWrite ensuredir) ReSTRenderer)IteratorSequenceSPHINX_APIDOC_OPTIONS,)membersz undoc-memberszshow-inheritancez.pyz.pyx templatesapidocfilename str | Pathreturnboolcs*t|jtfddtttddDS)z)Check *filename* is __init__ file or not.c3s|] }d|kVqdS)__init__N).0suffixbasenamerE/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/ext/apidoc.py ;s  zis_initpy..T)keyreverse)rnameanysorted PY_SUFFIXESlen)rrr!r# is_initpy8s   r,modnames str | NonestrcGsdtd|S)zJoin module names with dots..N)joinfilter)r-rrr# module_joinAsr3dirnamefileslist[str] | NonecCs8|dur |dur dS|durt|}tdd|DS)z+Check given *files* contains __init__ file.NFcs|] }t|r|VqdSNr,rfrrr#r$Mz is_packagedir..)oslistdirr()r4r5rrr# is_packagedirFs  r?r'textopts CliOptionsrcCst|j|d|j}|jr|jsttd||S|js0| r0|js.ttd||S|js;ttd|t |}| |Wd|S1sPwY|S)z0Write the output file for module/package .r0zWould create file %s.z!File %s already exists, skipping.zCreating file %s.N) rdestdirr dryrunquietloggerinfor forceis_filerwrite)r'r@rAfnamer;rrr# write_filePs"   rLpackager"user_template_dirc Csptt}|jrd|vr|dt||}|j |||d}|dur'|tg}ntg}t|d|}t |||S)z.Build the text of the file and write the file.private-members) show_headingsr"qualnameautomodule_optionsNzmodule.rst.jinja) rOPTIONSincludeprivateappendr3 noheadings template_dirrrenderrL) rMr"rArNoptionsrQcontext template_pathr@rrr#create_module_filebs    r\rrootmaster_packagesubrootpy_files list[str]subs is_namespaceexcludesSequence[re.Pattern[str]] list[Path]c  sfdd|D} fdd|D} tt| } fdd| D} tt} jr8d| vr8| dt} | | | |jj| j j d } durWt g}nt g}g}t | d| }|t| || rjr|fd d| D|S) zBuild the text of the file and write the file. Also create submodules if necessary. :returns: list of written files cs*g|]}tt|st|qSr)is_skipped_packagerr3)rpkgname)rdr^rAr]r_rr# s  z'create_package_file..cs4g|]}tt|st|s|ddqS)r0r)is_skipped_modulerr,splitrsub)rdrAr]rr#ris csg|]}t|qSr)r3)rmodname)r^r_rr#ris rO) rh subpackages submodulesrc modulefirstseparatemodulesrRrPmaxdepthNzpackage.rst.jinjacsg|] }td|qSr8)r\)r submodule)rArNrr#ris )r)setrrSrTrUr3rqrrrVrsrWrrXrLextend)r]r^r_r`rArbrcrdrNrorprYrhrZr[writtenr@r)rdr^rAr]r_rNr#create_package_file|sF      rxmodulesc Cs||d}|D]}||dr||q |}q |j|j|d}|dur-|tg}ntg}t|d|}t |||S)zCreate the module's index.r0)headerrsdocnamesNz toc.rst.jinja) sortr startswithremover{rsrWrrXrL) ryrAr'rN prev_modulemodulerZr[r@rrr#create_modules_toc_files    rcs\tsdStttd}tdd|D}|s"|js"dStfdd|DS)%Check if we want to skip this module.Fz*.pycsr7r8r9r:rrr#r$r<z%is_skipped_package..Tc3s |] }tt|VqdSr8) is_excludedrr:r4rdrr#r$s)ris_dirglobr/r(implicit_namespacesall)r4rArdr5regular_packagerrr#rgs  rg _excludescCs(t|}|s dS|jdo|j S)rT_)rexistsr'r~rT)rrArrrr#rjsrjrootpath*Iterator[tuple[str, list[str], list[str]]]c#sxtj||jdD]0\}}tfdd|D}|jr dndtfdd|D|dd<||fVq dS)z@Walk through the directory and list files and subdirectories up.) followlinksc3s.|]}|trtt|s|VqdSr8)endswithr*rrr:)rdr]rr#r$s zwalk..)r0)r0rc3s.|]}|stt|s|VqdSr8)r~rrrlexclude_prefixesrdr]rr#r$s N)r=walkrr)rT)rrdrArbr5rrr#rsrcCstddt|||DS)zACheck the given directory contains child module/s (at least one).css|]\}}}|VqdSr8r)r_root_subsr5rrr#r$z#has_child_module..)r(r)rrdrArrr#has_child_modulesrtuple[list[Path], list[str]]c Cst|s|jr|tjd}nd}g}g}t|||D]\}}} td| } | o+|j} | rE| D]} t| rC| | | d| q2n ||krQ|jsQ| q| sU| r|sbt | dksbt ||s|t |d tjtjd} | r{t|||r|t||| | ||| || |t|| q||ksJ|dusJ| D]!}tt||||s|dd}|t||||||qq||fS)z` Look for every file in the directory tree and create the corresponding ReST files. Nrr0)r?rrkrseprrr,rinsertclearr+rglstripreplacerrvrxrUr3rjrr\)rrdrArN root_package toplevels written_filesr]rbr5is_pkgrcr; subpackagepy_filerrrr# recurse_tree sj            rcst|tfdd|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|]}|VqdSr8)matchrexcluderoot_strrr#r$przis_excluded..)r/r()r]rdrrr#risrargparse.ArgumentParserc 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,|}|jdQddRtdSd|jdTdUddVtdWd|jdXdYddZtd[d|jd\d]dd^td_d|jd`daddbtdcd|jdddeddtdfd|jdgdhdditdjd|tdk}|jdldmdndotdpdqtD]}|jdr|dsdt|dntdu|dvqA|tdw}|jdxdydzd{td|d}|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-dirstorerCTzdirectory to place all output)rrrequiredrz-q store_truerEz,no output on stdout, just warnings on stderr)rrrz-dz --maxdepthrsz;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcerHzoverwrite existing filesz-lz--follow-linksrFzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rrrrz-nz --dry-runrDz%run the script without creating filesz-ez --separaterrz1put documentation for each module on its own pagez-Pz --privaterTzinclude "_private" modulesz --tocfiletocfileryz0filename of table of contents (default: modules)z-Tz--no-toc store_falsez%don't create a table of contents filez-Ez --no-headingsrVzedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrqz7put module documentation before submodule documentationz--implicit-namespacesrzNinterpret module paths according to PEP-0420 implicit namespaces specificationz-sz--suffixr rstzfile suffix (default: rst)z --remove-old remove_oldzERemove existing files in the output directory that were not generatedz-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-projectr{z(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 extensionsrUzenable 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_mutually_exclusive_groupadd_argument_groupr )parserexclusive_groupgroupextrrr# get_parserss       rc@seZdZUdZded<ded<ded<ded<d ed <ded <ded <ded <ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<d S)!rBz'Arguments parsed from the command line.r/rrarrCrrErrsrHrrDrrrTrrVrqrr rrr.r{rrrr6rrrN)__name__ __module__ __qualname____doc____annotations__rrrr#rBQs4  argv Sequence[str]rc Csttjdtjt}||ptjdd}t |j }|j dur/| t jd|_ |jd|_t|sHttd|td|jsPt|jtddt|jD}t||||j\}}|j r d d l!m"}|#d}d} |D]} | $|drq{| }| d | 7} q{id |jd dddd|j d|j%pdd|j&pdd|j'p|j&pddd|jdddddgdddddddd |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'n|j0r0|1t2|||j0|j|j3ru|jsut|j4d(|jD]0} | |vrsz| 5WqDt6yr}ztj7td)| |j8d*d+WYd}~qDd}~wwqDd S),z+Parse and check the command line arguments.rzrNrr0z%s is not a directory.css&|]}ttt|VqdSr8)recompilefnmatch translaterabspathrrrr#r$s  zmain..r) quickstartz %s rrFdotrprojectrAuthorrrr masterindexepubTr)zsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todomakefile batchfile make_modemastertocmaxdepth mastertoctreelanguageen)rrrEr)silent overwriterz**/*.zFailed to remove %s: %sautodoc)r)9locale setlocaleLC_ALLsphinx init_consoler parse_argssysrrrrr{rkrr removeprefixrrrFerrorr SystemExitrDrrCtupledictfromkeysrrrr sphinx.cmdrr}r~rrrrsrrrvrErgeneraterHrrUrrrunlinkOSErrorwarningstrerror)rrargsrrdrryqsrr@rdrexistingexcrrr#mainns                 r__main__r)rrrr)r-r.rr/)NN)r4r.r5r6rr)r'r/r@r/rArBrrr8) rMr.r"r/rArBrNr.rr)rN)r]r/r^r.r_r/r`rarArBrbrarcrrdrerNr.rrf)ryN) ryrarArBr'r/rNr.rr)r)r4rrArBrdrerr)rrrArBrrerr)rr/rdrerArBrr)rr/rdrerArBrr) rr/rdrerArBrNr.rr)r]rrdrerr)rr)rrrr)Ar __future__rrrrrr=rrrimportlib.machineryrrpathlibrtypingrrr sphinx.localerr r sphinx.cmd.quickstartr r sphinx.utilrsphinx.util.osutilrrsphinx.util.templatercollections.abcrr getLoggerrrFenvironrkrSrr*r1rWr,r3r?rLr\rxrrgrjrrrrrrBrrrrrrr#sp               " G    I _  b