7 f.NdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z ddlm Z ddlmZmZddlZddlmZmZdd lmZdd lmZdd lmZdd lmZmZdd lmZerddlm Z m!Z!ej"e#Z$dej%vr!ej%d&dZ'ngdZ'de(e zZ)e j*eddZ+dIdZ,dJdZ-dKdLd Z.dMd&Z/ dNdOd*Z0 dPdQd5Z1 dRdSd7Z2 dTdUd8Z3dVd:Z4dWd=Z5dXd>Z6 dNdYd?Z7dZd@Z8d[dBZ9dTd\dFZ:e#dGkr!e;e:e j<dHddS)]uCreates 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) TYPE_CHECKINGAny)__display_version__ package_dir) EXTENSIONS)__)logging)FileAvoidWrite ensuredir) ReSTRenderer) GeneratorSequenceSPHINX_APIDOC_OPTIONS,)membersz undoc-memberszshow-inheritance)z.pyz.pyx templatesapidocfilenamestrreturnboolctj|tfdttt dDS)z)Check *filename* is __init__ file or not.c3*K|] }d|zkVdS)__init__N).0suffixbasenames G/var/www/equiseq/venv/lib/python3.11/site-packages/sphinx/ext/apidoc.py zis_initpy..:sA  J''T)keyreverse)rr"anysorted PY_SUFFIXESlen)rr"s @r# is_initpyr,7sY}X&&H [c4@@@  r%modnames str | NonecHdtd|S)zJoin module names with dots..N)joinfilter)r-s r# module_joinr3@s 88F4** + ++r%dirnamefileslist[str] | Nonecl||dS|tj|}td|DS)z+Check given *files* contains __init__ file.NFc38K|]}t||VdSNr,r fs r#r$z is_packagedir..Ls-00Q9Q<<0q000000r%)oslistdirr()r4r5s r# is_packagedirr?EsA }u } 7## 00%000 0 00r%nametextoptsrNonec6t|dd}tj|j|d|j}|jr,|s(t td|dS|j sBtj |r.|s*t td|dSdS|s(t td|t|5}| |ddddS#1swxYwYdS)z0Write the output file for module/package .quietNr0zWould create file %s.z!File %s already exists, skipping.zCreating file %s.) getattrrr1destdirr!dryrunloggerinfor forceisfilerwrite)r@rArBrEfnamer<s r# write_filerOOsb D'4 ( (E Idlt$;$;dk$;$; < ?? G G G G G H H 8 KK.// 7 7 7 E " " a GGDMMM                  s+DDDpackager"user_template_dirc8tt}|jrd|vr|dt ||}|j |||d}| |t g}nt g}t|d|}t|||dS).Build the text of the file and write the file.private-members) show_headingsr"qualnameautomodule_optionsNz module.rst_t) rOPTIONSincludeprivateappendr3 noheadings template_dirrrenderrO) rPr"rBrQoptionsrVcontext template_pathrAs r#create_module_filerabs7mmG *0??()))7H--H!_,% G $*L9 %  & & - -ng F FDxt$$$$$r%rrootmaster_packagesubrootpy_files list[str]subs is_namespaceexcludesSequence[re.Pattern[str]]c Lfd|D} fd|D} tt| } fd| D} tt} jrd| vr| dt } | | | |jj| j j d } | |tg}ntg}t| d| }t| || rjr| D]}td||dSdSdS)rSczg|]7}ttj|&t|8Sr)is_skipped_packagerr1r3)r pkgnamerircrBrbrds r# z'create_package_file..sYXXX,TYtW-E-EtXVVX;~w@@XXXr%cg|]P}ttj|&t|5|ddQS)r0r)is_skipped_modulerr1r,split)r subrirBrbs r#roz'create_package_file..sb&&&*49T3+?+?xPP&nn&#))C..#&&&r%c2g|]}t|Sr)r3)r modnamercrds r#roz'create_package_file..s5---ngw??---r%rT) rn subpackages submodulesrh modulefirstseparatemodulesrWrUmaxdepthNz package.rst_t)r)setrrXrYrZr3rxryr[rzr\rr]rOra)rbrcrdrerBrgrhrirQrvrwr^rnr_r`rA submodules``` ` ` r#create_package_filer}xsXXXXXXXX"&XXXK&&&&&&x&&&JJ((J-----!+---J7mmG *0??())).'22G" $'/%!_,M  G$*L9 %  & & - -ow G GDwd###Id*I# I II tY6G H H H HIIII I Ir%modulesc\|d}|ddD]2}||dzr||0|}3|j|j|d}| |t g}nt g}t |d|}t|||dS)zCreate the module's index.Nr0)headerrzdocnamesz toc.rst_t) sort startswithremoverrzr\rr]rO) r~rBr@rQ prev_modulemoduler_r`rAs r#create_modules_toc_filers LLNNNK!!!*!!   [3. / / ! NN6 " " " " KK+MG $*L9 %  & & - -k7 C CDtT4     r%ctjsdStjtjd}t d|D}|s |jsdSt fd|DS)%Check if we want to skip this module.Fz*.pyc38K|]}t||VdSr9r:r;s r#r$z%is_skipped_package..s-;;ill;!;;;;;;r%Tc3^K|]'}ttj|V(dSr9) is_excludedrr1)r r<r4ris r#r$z%is_skipped_package..s9KK{49Wa00(;;KKKKKKr%)risdirglobr1r(implicit_namespacesall)r4rBrir5regular_packages` ` r#rmrms :g  u Idi00 1 1E;;U;;;;;O 4#;t KKKKKUKKK K KKr% _excludesctj|sdStj|dr |jsdSdS)rT_F)rexistsr"rrY)rrBrs r#rqrqsM ;x t }X))#..t7Jt 5r%rootpath7Generator[tuple[str, list[str], list[str]], None, None]c#&Kt|dd}t|dd}tj||D]R\}}tfd|D}|rdndtfd|D|d d <||fVSd S) z@Walk through the directory and list files and subdirectories up. followlinksFrY)rc3K|]C}|tttj|?|VDdSr9)endswithr*rrr1)r r<rirbs r#r$zwalk..soFFQ**[11F&tyq'9'98DDFqFFFFFFr%)r0)r0rc3K|]>}|ttj|:|V?dSr9)rrrr1)r rsexclude_prefixesrirbs r#r$zwalk..soJJCNNCS4T4TJ(4)=)=xHHJJJJJJJr%N)rFr=walkr)) rrirBrrYrgr5rrbs ` @@r#rrs"$ u55KT#3U;;NWX;GGG  dEFFFFF%FFFFF  *06  ) JJJJJJJJJJJQQQD%!  r%cRtdt|||DS)zACheck the given directory contains child module/s (at least one).c3"K|] \}}}|V dSr9r)r _root_subsr5s r#r$z#has_child_module..s< E5% r%)r(r)rrirBs r#has_child_modulers< #'(D#A#A  r%c .t|dd}t|s|r&|tjd}nd}g}t |||D]\}}} td| } | o|} | rH| ddD]<} t | r+| | | d| =n||kr|s|dd=t| s| r|s#t| dkst||s|t|d tj tjd} | rt|||r:t||| | ||| || |t!|| >||ksJ|J| D]h}t#tj||||sB|dd}t'||||||i|S)z` Look for every file in the directory tree and create the corresponding ReST files. rFNrr0)rFr?rrrseprr,rinsertr+rmlstripreplacerr}rZr3rqr1ra)rrirBrQr root_package toplevelsrbrgr5is_pkgrhr< subpackagepy_filers r# recurse_treers} "$(=uEEX"5~~dh//3  I!(Hd;;"-"-dEtU++!z9&9  111X ' 'Q<<'LLOOOLLA&&& 'X  & G  -\ - Ls5zzA~~-?d-K-K~!#h--..188BBGDHc**$L'7h'M'ML'lJ(-tT<(9;;;$$[z%J%JKKK8####'''  - -(8W)E)EtXVV-$]]3//2F&|VTCTUUU$$V,,,  - r%c:tfd|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". c3BK|]}|VdSr9)match)r excluderbs r#r$zis_excluded..8s/;;ww}}T"";;;;;;r%)r()rbris` r#rr2s( ;;;;(;;; ; ;;r%argparse.ArgumentParserc tjdtdtd}|ddddtz |d td  |d dtd|dddddtd|dddtd|ddddt d td!"|d#d$dd%td&|d'd(dd)d*td+,|d-d.dd/td0|d1d2dd3td4|d5d6dd7td8|d9dd:d;td<,|d=d>d?d:td@|dAdBddCtdD|dEdFddGtdH|dIddJtdK|dLdMddNdOtdP,|dQdRddStdT|dUdVddWtdX|dYdZdd[td\|d]d^dd_td`|dadbddtdc|dddeddftdg|tdh}|didjdkdltdmntD]2}|do|zdpdq|zdktdr|zs3|tdt}|dudvdwdxtdyz|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-dirstorerGTzdirectory to place all output)rrrequiredrz-q store_truerEz,no output on stdout, just warnings on stderr)rrrz-dz --maxdepthrzz;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcerKzoverwrite existing filesz-lz--follow-linksrFzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)rrrrz-nz --dry-runrHz%run the script without creating filesz-ez --separateryz1put documentation for each module on its own pagez-Pz --privaterYzinclude "_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-headingsr[zedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrxz7put module documentation before submodule documentationz--implicit-namespacesrzNinterpret 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-projectrz(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 extensionsrZzenable 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 )parsergroupexts r# get_parserr;s*  $'NOOJKK L L LF  IN .1D DFFF   <==??? )!=>>??? nW9!% ?@@BBB \ NOOQQQ l7 !!/00111 i 7 :;;=== .|*E!CDDEEE k,X GHHJJJ l<. STTVVV k,- <==???  G)Y RSSUUU jY GHHJJJ ol)!011222  .|*!011222 / 2!DEEFFF jx % <==??? h|& PQQSSS 0- [\\^^^ ogH JKKMMM nW8 NOOQQQ ogI LMMOOO ogI!<==>>>  % %b)<&=&= > >E ~|,&R0M-N-NPPPAA :+N!03!6\ "#8 9 9C ?  A A A A  % %b)=&>&> ? ?E t_m)FGGIII Mr%argv Sequence[str]rctjtjdtjt }||ptjdd}tj |j }|j *| tjd|_ |jdr|jdd|_tj|s7t$t)d|t+d|jst/|jt3dt4|jD}t;||||j}|jrxdd l m!}|"d}d}|D]%} | |dzr| }|d | zz }&id |jd d ddd|j d|j#pdd|j$pdd|j%p|j$pddd|jzdddddgdddddddd|j&d |d!d"||j'd#} |j(r | d)|j(|j*rd| d$<| dddD]O} d%| vrI| d+| | d)| d%P|js#|,| d|j-|j&n#|j.rt_|||j.|jdS)'z+Parse and check the command line arguments.rrNrr0z%s is not a directory.c3K|]<}tjtjt j|V=dSr9)recompilefnmatch translaterabspath)r rs r#r$zmain..sU  7$T\'%:%:;;<<r%r) quickstartz %s rrFdotrprojectrAuthorrrr!masterindexepubTr)zsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todomakefile batchfile make_modemastertocmaxdepth mastertoctreelanguageen)rrrEr)silent overwriter)0locale setlocaleLC_ALLsphinx init_consoler parse_argssysrrrrrrrrr!rrrIerrorr SystemExitrHrrGtupledictfromkeysrrrr sphinx.cmdrrrrrrzrrextendrErgeneraterKrr) rrargsrrir~qsrrArdrs r#mainr s V]B''' M   \\F   T1SXabb\ 2 2D|D,--H {nnTX..r2  {c""&k!""o :h   R0118<<<mm ; $,}}T%9::H8XtT5EFFG y.O//////   ' 'F  s!233  K I& &DD DL 5  3  t{  dk-X  t|)r   t|9t|9r  cDK'  g  D  ...       ! " T# $ % &$"1)   , ? 4 lO " "4? 3 3 3 : AgJ\?111% 7 7Cczz,&&s+++,&&syy~~666{ 6 KK$$*$($4  6 6 6 Ot|T=MNNN 1r%__main__r)rrrr)r-r.rr)NN)r4r.r5r6rr)r@rrArrBrrrCr9) rPr.r"rrBrrQr.rrC)rN)rbrrcr.rdrrerfrBrrgrfrhrrirjrQr.rrC)r~N) r~rfrBrr@rrQr.rrC)r)r4rrBrrirjrr)rrrBrrrjrr)rrrirjrBrrr)rrrirjrBrrr) rrrirjrBrrQr.rrf)rbrrirjrr)rr)rrrr)=__doc__ __future__rrrrrr=rrrimportlib.machineryrrtypingrr sphinx.localerr r sphinx.cmd.quickstartr r sphinx.utilr sphinx.util.osutilrrsphinx.util.templatercollections.abcrr getLogger__name__rIenvironrrrXrr*r1r\r,r3r?rOrar}rrmrqrrrrrr rrrr%r#rs  #""""" 222222%%%%%%%%33333333,,,,,,88888888------433333333  8 $ $bj((j0177<@ L L L L L     22644444n<<<<^^^^BK K K K K ^ z *TT#(122,'' ( ((r%