Fe.NdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z ddlm Z ddlmZmZddlZddlmZmZdd lmZdd lmZdd lmZdd lmZmZdd lmZerddlm Z m!Z!ejDe#Z$dejJvrejJdjMdZ'ngdZ'de(e zZ)e jTeddZ+d&dZ,d'dZ-d(d)dZ.d*dZ/ d+ d,dZ0 d- d.dZ1 d/ d0dZ2 d1 d2dZ3d3dZ4 d4dZ5d5dZ6 d+ d6d Z7d7d!Z8d8d"Z9d1d9d#Z:e#d$k(re;e:e jxd%dy):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 templatesapidocc~tj|tfdttt dDS)z)Check *filename* is __init__ file or not.c3.K|] }d|zk(yw)__init__N).0suffixbasenames 3/usr/lib/python3/dist-packages/sphinx/ext/apidoc.py zis_initpy..:s#  J''sT)keyreverse)rranysorted PY_SUFFIXESlen)filenamers @r is_initpyr(7s4}}X&H [c4@ c8djtd|S)zJoin module names with dots..N)joinfilter)modnamess r module_joinr/@s 88F4* ++r)c^||y|tj|}td|DS)z+Check given *files* contains __init__ file.Fc38K|]}t|s|ywNr(rfs rr z is_packagedir..Ls0Q9Q.quietNr+zWould create file %s.z!File %s already exists, skipping.zCreating file %s.) getattrrr,destdirrdryrunloggerinfor forceisfilerwrite)nametextoptsr=fnamer5s r write_filerJOs D'4 (E IIdlltfAdkk]$; ? G KK./ 7 E " a GGDM   s C66C?ctt}|jrd|vr|jdt ||}|j |||d}| |t g}nt g}t|jd|}t|||y).Build the text of the file and write the file.private-members) show_headingsrqualnameautomodule_optionsNz module.rst_t) rOPTIONSincludeprivateappendr/ noheadings template_dirrrenderrJ) packagerrHuser_template_diroptionsrOcontext template_pathrGs rcreate_module_filer\bs7mG 0?()7H-H!__,% G $*L9 %  & - -ng FDxt$r)c .|D cgc]0} ttj|| ||s t||| 2} } |D cgc]B} t tj|| ||st | s| j ddD} } tt| } | D cgc]} t||| } } tt}|jrd|vr|jdt||} | | | ||j|j||j |j d }| |t"g}nt"g}t%|j'd|}t)| ||| r#|jr| D]}t+d|||yyycc} wcc} wcc} w)rLr+rrM) pkgname subpackages submodules is_namespace modulefirstseparatemodulesrPrNmaxdepthNz package.rst_t)is_skipped_packagerr,r/is_skipped_moduler(splitr$setrrQrRrSrbrcrTrdrUrrVrJr\)rootmaster_packagesubrootpy_filesrHsubsraexcludesrXr^r_subr`modnamerYrZr[rG submodules rcreate_package_filerrxs#'X,TYYtW-EtXV~w@XKX08&*499T3+?xPn))C.#&J&J(J!+-ngw?-J-7mG 0?().'2G" $''//%!__,MM G$*L9 %  & - -ow GDwd#d**# II tY6G H I+zCX&-s5FAF !Fc4|jd}|ddD]*}|j|dzr|j|)|},|j|j|d}| |t g}nt g}t |jd|}t|||y)zCreate the module's index.Nr+)headerrddocnamesz toc.rst_t) sort startswithremoverurdrUrrVrJ) modulesrHrFrX prev_modulemodulerZr[rGs rcreate_modules_toc_filer}s LLNK!*!   [3. / NN6 " K !++MMG $*L9 %  & - -k7 CDtT4 r)ctjsytjtjd}t d|D}|s |j syt fd|DS)%Check if we want to skip this module.Fz*.pyc38K|]}t|s|ywr2r3r4s rr z%is_skipped_package..s;il!;r6Tc3^K|]$}ttj|&ywr2) is_excludedrr,)rr5r9rns rr z%is_skipped_package..s#K{499Wa0(;Ks*-)risdirglobr,r#implicit_namespacesall)r9rHrnr:regular_packages` ` rreres^ ::g  IIdii0 1E;U;;O 4#;#; KUK KKr)ctj|sytj|jdr |jsyy)rT_F)rexistsrrxrR)r'rH _excludess rrfrfs6 ;;x  }}X))#.t7J7J r)c#Kt|dd}t|dd}tj||D]B\}}tfd|D}|rdndtfd|D|d d ||fDy w) z@Walk through the directory and list files and subdirectories up. followlinksFrR)rc3K|];}|jtr$ttj|s|=ywr2)endswithr%rrr,)rr5rnris rr zwalk..s;FQ**[1&tyyq'98DFsAA)r+)r+rc3K|]8}|jrttj|s|:ywr2)rxrrr,)rroexclude_prefixesrnris rr zwalk..s;JCNNCS4T(4)=xHJs A'AN)r>r7walkr$) rootpathrnrHrrRrmr:rris ` @@rrrs$ u5KT#3U;NWWX;G dEF%FF 06 ) JJJQD%! sA8A=c<tdt|||DS)zACheck the given directory contains child module/s (at least one).c3(K|] \}}}| ywr2r)r_root_subsr:s rr z#has_child_module..s E5% s)r#r)rrnrHs rhas_child_modulers% #'(D#A r)c t|dd}t|s|r#|jtjd}nd}g}t |||D]t\}}} td| } | xr|} | r:| ddD]1} t | s| j| | jd| 3n ||k7r|s|dd=d| s| r|st| dkDs t||r|t|djtjjtjd} | rt|||st||| | ||| || |jt!|| ||k(sJ|J| D]W}t#tj$||||r%|jdd}t'|||||j|Yw|S)z` Look for every file in the directory tree and create the corresponding ReST files. rFNrr+)r>r;rgrseprr(ryinsertr&relstripreplacerrrrSr/rfr,r\)rrnrHrXr root_package toplevelsrirmr:is_pkgrar5 subpackagepy_filer|s r recurse_treers "$(=uEX"5~~dhh/3  I!(Hd;"-dEtU+!z9&9 1X 'Q<LLOLLA& 'X &G \s5zA~-?d-K!#h-.188BGDHHc*$'7h'M'lJ(-tT<(9;$$[z%JK8# ##' ''  -(8W)EtXV$]]3/2F&|VTCTU$$V,  -="-H 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". c3@K|]}|jywr2)match)rexcluderis rr zis_excluded..8s;ww}}T";s)r#)rirns` rrr2s ;(; ;;r)c 4tjdtdtd}|jddddtz |jd td  |jd dtd|jdddddtd|jdddtd|jddddt d td!"|jd#d$dd%td&|jd'd(dd)d*td+,|jd-d.dd/td0|jd1d2dd3td4|jd5d6dd7td8|jd9dd:d;td<,|jd=d>d?d:td@|jdAdBddCtdD|jdEdFddGtdH|jdIddJtdK|jdLdMddNdOtdP,|jdQdRddStdT|jdUdVddWtdX|jdYdZdd[td\|jd]d^dd_td`|jdadbddtdc|jdddeddftdg|j tdh}|jdidjdkdltdmntD]*}|jdo|zdpdq|zdktdr|zs,|j tdt}|jdudvdwdxtdyz|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 --maxdepthrdz;maximum depth of submodules to show in the TOC (default: 4))rrtypedefaultrz-fz--forcerCzoverwrite 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 --separatercz1put documentation for each module on its own pagez-Pz --privaterRzinclude "_private" modulesz --tocfiletocfilerzz0filename of table of contents (default: modules)z-Tz--no-toc store_falsez%don't create a table of contents filez-Ez --no-headingsrTzedon't create headings for the module/package packages (e.g. when the docstrings already contain them)z-Mz--module-firstrbz7put module documentation before submodule documentationz--implicit-namespacesrzNinterpret 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-projectruz(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 extensionsrSzenable 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  $ $'NOJK LF  IN .1D DF   <=? )!=>? nW9!% ?@B \ NOQ l7 !!/01 i 7 :;= .|*E!CDE k,X GHJ l<. STV k,- <=?  G)Y RSU jY GHJ ol)!012  .|*!012 / 2!DEF jx % <=? h|& PQS 0- [\^ ogH JKM nW8 NOQ ogI LMO ogI!<=>  % %b)<&= >E ~|,&R0M-NPA :+N!03!6\ "#8 9C ?  AA  % %b)=&> ?E t_m)FGI Mr)ctjtjdtjj t }|j |xstjdd}tj|j}|j'|jtjd|_ |jj!dr|jdd|_tj"|s*t$j't)d|t+d|j,st/|j0t3dt4j7|j8D}t;||||j<}|j>rdd l m!}|jEd}d}|D]!} | j!|dzr| }|d | zz }#id |j0d d ddd|jd|jFxsdd|jHxsdd|jJxs|jHxsddd|jzdddddgdddddddd|jLd |d!d"||jNd#} |jPr| djS|jP|jTrd| d$<| dddD]>} d%| vs| djW| | djS| jd%@|j,s)|jY| d|jZ|j<&y|j\r"t_|||j\|j<y)'z+Parse and check the command line arguments.rtrNrr+z%s is not a directory.c3K|]?}tjtjt j |Aywr2)recompilefnmatch translaterabspath)rrs rr zmain..s5  7$$T\\'%:;<sAAr) quickstartz %s rrFdotrprojectrAuthorrrrmasterindexepubTr)zsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todomakefile batchfile make_modemastertocmaxdepth mastertoctreelanguageen)rrr=r)silent overwriter)0locale setlocaleLC_ALLsphinx init_consoler parse_argssysargvrrrrurgrrrxrrAerrorr SystemExitr@rr?tupledictfromkeysrrrr sphinx.cmdrrwrrrrdrrextendr=rygeneraterCrr}) rrargsrrnrzqsr{rGr|drs rmainrsg V]]B' MM \F   T1SXXab\ 2D||D,,-H {{nnTXX.r2  {{c"kk!"o ::h  R018<m ;;$,,}}T%9%9:H8XtT5E5EFG yy/   'F  s!23 K I& &D  '  DLL 5  3  t{{  dkk-X  t||)r   t||9t||9r  cDKK'  g  D  .       ! " T# $ % &$"11) , ?? lO " "4?? 3 ::AgJ\?1% 7Ccz,&&s+,&&syy~6 7 {{ KK$$**$($4$4  6  t||T=M=MN r)__main__r)r'strreturnbool)r. str | Nonerr)NN)r9rr:zlist[str] | Nonerr)rFrrGrrHrrNoner2) rWrrrrHrrXrrr)rN)rirrjrrkrrl list[str]rHrrmrrarrnSequence[re.Pattern[str]]rXrrr)rzN) rzrrHrrFrrXrrr)r)r9rrHrrnrrr)r'rrHrrrrr)rrrnrrHrrz7Generator[tuple[str, list[str], list[str]], None, None])rrrnrrHrrr) rrrnrrHrrXrrr)rirrnrrr)rzargparse.ArgumentParser)rz Sequence[str]rr)=__doc__ __future__rrrrrr7rrrimportlib.machineryrrtypingrr sphinx.localerr r sphinx.cmd.quickstartr r sphinx.utilr sphinx.util.osutilrrsphinx.util.templatercollections.abcrr getLogger__name__rAenvironrgrQrr%r,rUr(r/r;rJr\rrr}rerfrrrrrrrrrr)rrs # 2%3,8-3   8 $bjj(jj0177@ L!: LDH L  E 2264$.4:C4n<^BK ^ z T#((12,' ((r)