3
T'ícKK ã @ s® d Z ddlZddlZddlZddlZddlZddlmZ ddlmZ ddlm Z ddlm
Z
ddl m Z m
Z
mZmZ ddlZddlmZmZ dd lmZ dd
lmZ dd lmZmZ dd lmZ d
ej krÜej d
j dZ n
dddgZ dEe e Z e
j!eddZ"e#e$dddZ%e#e#dddZ&dFe#ee# e$d d d Z'e#e#e dd d d!Z(dGe#e#e e#dd"d#d$Z)g dfe#e#e#ee# e ee# e$ee# e#dd%
d&d'Z*dHee# e e#e#dd)d*d+Z+g fe#e ee# e$d,d-d.Z,e#e ee# e$d/d0d1Z-e#ee# e e
ee#ee# ee# f ddf d2d3d4Z.e#ee# e e$d2d5d6Z/dIe#ee# e e#ee# d7d8d9Z0e#ee# e$d:d;d<Z1ej2d=d>d?Z3ej4d@d
fee# e5dAdBdCZ6e7dDkrªe6 dS )Ju¢ Creates 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.<suffix>).
This is derived from the "sphinx-autopackage" script, which is:
Copyright 2008 Société des arts technologiques (SAT),
https://sat.qc.ca/
é N)Úcopy)Úfnmatch)ÚEXTENSION_SUFFIXES)Úpath)ÚAnyÚ GeneratorÚListÚTuple)Ú__display_version__Ú package_dir)Ú
EXTENSIONS)Ú__)ÚFileAvoidWriteÚ ensuredir)Ú ReSTRendererZSPHINX_APIDOC_OPTIONSú,Úmembersz
undoc-memberszshow-inheritanceú.pyú.pyxZ templatesZapidoc)ÚfilenameÚreturnc C s: t j| }x*tttddD ]}|d| krdS qW dS dS )z)Check *filename* is __init__ file or not.T)ÚkeyÚreverseÚ__init__FN)r ÚbasenameÚsortedÚ PY_SUFFIXESÚlen)r r Úsuffix© r ú3/tmp/pip-build-gk9425m9/sphinx/sphinx/ext/apidoc.pyÚ is_initpy. s
r! )Úmodnamesr c G s dj td| S )z Join module names with dots.Ú.N)ÚjoinÚfilter)r" r r r Ú module_join8 s r& )ÚdirnameÚfilesr c C s8 |dkr| dkrdS |dkr&t j| }tdd |D S )z+Check given *files* contains __init__ file.NFc s s | ]}t |r|V qd S )N)r! )Ú.0Úfr r r ú <genexpr>D s z is_packagedir.<locals>.<genexpr>)ÚosÚlistdirÚany)r' r( r r r Ú
is_packagedir= s
r/ )ÚnameÚtextÚoptsr c C s t |dd}tj|jd| |jf }|jrB|s>ttd| dS |j rjtj |rj|sttd| n2|s~ttd| t
|}|j | W dQ R X dS )z0Write the output file for module/package <name>.ÚquietNz%s.%szWould create file %s.z!File %s already exists, skipping.zCreating file %s.) Úgetattrr r$ Údestdirr ÚdryrunÚprintr
ÚforceÚisfiler Úwrite)r0 r1 r2 r3 Úfnamer* r r r Ú
write_fileG s
r< )Úpackager r2 Úuser_template_dirr c C s` t t}|jr d|kr |jd t| |}|j |||d}t|tgjd|}t ||| dS )z.Build the text of the file and write the file.zprivate-members)Ú
show_headingsr ÚqualnameÚautomodule_optionsz module.rst_tN)
r ÚOPTIONSÚincludeprivateÚappendr& Ú
noheadingsr Ú template_dirÚrenderr< )r= r r2 r> Úoptionsr@ Úcontextr1 r r r Úcreate_module_fileZ s
rJ )
ÚrootÚmaster_packageÚsubrootÚpy_filesr2 ÚsubsÚ is_namespaceÚexcludesr> r c
sÚ fdd|D } fdd|D }
fdd|
D }
t t} jrdd| krd| jd t} | | |
|jj| j jd }
t |t
gj d|
}t | | |
rÖjrÖx|
D ]}t
d|| qÀW dS ) z.Build the text of the file and write the file.c s, g | ]$}t tj| st|qS r )Úis_skipped_packager r$ r& )r) Úpkgname)rQ rL r2 rK rM r r ú
<listcomp>q s z'create_package_file.<locals>.<listcomp>c s: g | ]2}t tj| rt| r|jd d qS )r# r )Úis_skipped_moduler r$ r! Úsplit)r) Úsub)rQ r2 rK r r rT u s c s g | ]}t |qS r )r& )r) Úmodname)rL rM r r rT x s zprivate-members) rS Ú subpackagesÚ
submodulesrP Ú modulefirstÚseparatemodulesrA r? Úmaxdepthz
package.rst_tN)r rB rC rD r& r[ r\ rE r] r rF rG r< rJ )rK rL rM rN r2 rO rP rQ r> rY rZ rH rS rI r1 Ú submoduler )rQ rL r2 rK rM r Úcreate_package_filel s.
r_ Úmodules)r` r2 r0 r> r c C st | j d}x2| dd
D ]"}|j|d r8| j| q|}qW |j|j| d}t|tgjd|}t||| dS )zCreate the module's index.Ú Nr# )Úheaderr] Zdocnamesz toc.rst_t) ÚsortÚ
startswithÚremoverb r] r rF rG r< )r` r2 r0 r> Ú prev_moduleÚmodulerI r1 r r r Úcreate_modules_toc_file s rh )r' r2 rQ r c sh t j sdS tjt j d}tdd |D }| rD|j rDdS t fdd|D r`dS dS dS )z%Check if we want to skip this module.Fz*.pyc s s | ]}t |r|V qd S )N)r! )r) r* r r r r+ s z%is_skipped_package.<locals>.<genexpr>Tc 3 s | ]}t tj |V qd S )N)Ú is_excludedr r$ )r) r* )r' rQ r r r+ ³ s N)r ÚisdirÚglobr$ r. Úimplicit_namespacesÚall)r' r2 rQ r( Zregular_packager )r' rQ r rR § s
rR )r r2 rQ r c C s2 t j| sdS t j| jdr*|j r*dS dS dS )z%Check if we want to skip this module.TÚ_FN)r Úexistsr rd rC )r r2 rQ r r r rU º s
rU )ÚrootpathrQ r2 r c # s t |dd}t |dd}xptj| |dD ]^\}}tfdd|D }|rTd nd t fd d|D |d
d
< ||fV q(W d
S )
z@Walk through the directory and list files and subdirectories up.Ú followlinksFrC )rq c 3 s0 | ](}|j trttj| r|V qd S )N)Úendswithr ri r r$ )r) r* )rQ rK r r r+ Î s
zwalk.<locals>.<genexpr>r# rn c 3 s2 | ]*}|j rttj| r|V qd S )N)rd ri r r$ )r) rW )Úexclude_prefixesrQ rK r r r+ Ù s N)r# )r# rn )r4 r, Úwalkr )rp rQ r2 rq rC rO r( r )rs rQ rK r rt Æ s "rt c C s( x"t | ||D ]\}}}|rdS qW dS )zACheck the given directory contains child module/s (at least one).TF)rt )rp rQ r2 Ú_rootZ_subsr( r r r Úhas_child_moduleß s rv )rp rQ r2 r> r c C sª t |dd}t| s|r*| jtjd }nd}g }xpt| ||D ]^\}}} td| }
|
o`|} |
rxL| dd
D ]"} t| rt| j| | jd| qtW n|| kr´|s´|dd
= qB|
s¾| r>|sÜt | dksÜt
|| r¢|t | d
j tjj tjd}
| st
|||r¢t|||
| ||| || |jt||
qB|| krR|dksVtxJ| D ]B}ttj| |||s\|jdd }t|||| |j| q\W qBW |S )z`
Look for every file in the directory tree and create the corresponding
ReST files.
rl Fé Nr r# éÿÿÿÿ)r4 r/ rV r Úseprt r! re Úinsertr rR ÚlstripÚreplacerv r_ rD r& ÚAssertionErrorrU r$ rJ )rp rQ r2 r> rl Z root_packageZ toplevelsrK rO r( Zis_pkgrP r* Z
subpackageZpy_filerg r r r Ú recurse_treeè sB
r~ )rK rQ r c C s x|D ]}t | |rdS qW dS )zÄCheck 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 )rK rQ Úexcluder r r ri s
ri )r c C s¾ t jdtdtdd} | jddddt d | jd
td d | jd
dtdd | jdddddtdd | jdddtdd | jd d dd td 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 | jtdh}|jdidjdkdltdmdn x2tD ]*}|jdo| dpdq| dktdr| ds qfW | jtdt}|jdudvdwdxtdydz | S ){NzH%(prog)s [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]z:For more information, visit <https://www.sphinx-doc.org/>.aE
Look recursively in <MODULE_PATH> for Python modules and packages and create
one reST file with automodule directives per package in the <OUTPUT_PATH>.
The <EXCLUDE_PATTERN>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.)ÚusageÚepilogÚ descriptionz --versionÚversionZ show_versionz %%(prog)s %s)ÚactionÚdestr Ú module_pathzpath to module to document)ÚhelpÚexclude_patternÚ*zGfnmatch-style file and/or directory patterns to exclude from generation)Únargsr z-oz --output-dirÚstorer5 Tz directory to place all output)r r
Úrequiredr z-qÚ
store_truer3 z,no output on stdout, just warnings on stderr)r r
r z-dz
--maxdepthr] é z;maximum depth of submodules to show in the TOC (default: 4))r r
ÚtypeÚdefaultr z-fz--forcer8 zoverwrite existing filesz-lz--follow-linksrq FzNfollow symbolic links. Powerful when combined with collective.recipe.omelette.)r r
r r z-nz --dry-runr6 z%run the script without creating filesz-ez
--separater\ z1put documentation for each module on its own pagez-Pz --privaterC zinclude "_private" modulesz --tocfileÚtocfiler` z0filename of table of contents (default: modules)z-Tz--no-tocÚ store_falsez%don't create a table of contents filez-Ez
--no-headingsrE 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-namespacesrl zNinterpret module paths according to PEP-0420 implicit namespaces specificationz-sz--suffixr Zrstzfile suffix (default: rst)z-Fz--fullÚfullz.generate a full project with sphinx-quickstartz-az--append-syspathÚappend_syspathz9append module_path to sys.path, used when --full is givenz-Hz
--doc-projectrb z(project name (default: root module name)z-Az --doc-authorÚauthorz,project author(s), used when --full is givenz-Vz
--doc-versionz*project version, used when --full is givenz-Rz
--doc-releaseÚreleasezEproject release, used when --full is given, defaults to --doc-versionzextension optionsz --extensionsr Ú
extensionsrD zenable arbitrary extensions)Úmetavarr
r r z--ext-%sÚ append_constz
sphinx.ext.%szenable %s extension)r Úconstr
r zProject templatingz-tz
--templatedirZ TEMPLATEDIRÚ templatedirz%template directory for template files)r r
r )ÚargparseÚArgumentParserr
Ú add_argumentr
ÚintÚadd_argument_groupr )ÚparserÚgroupÚextr r r Ú
get_parser* s
r¤ rw )Úargvr c C s< t jjtjd t jjtjjtdd t }|j
| }tj |j }|j
dkr`|jtjd |_
|jjdr||jdd
|_tj|s¦ttd| tjd tjd |js¶t|j d d
|jD }t ||||j }|j r d d l m } |j! d}d}x2|D ]*} | j|d rq | }|d
| 7 }q W |jdd|j
|j"pDd|j#pNd|j$p`|j#p`dd|j dddddgddd|j%|d||j&d}
|j'r¦|
d j(|j' |j)r¶d|
d< xF|
d dd
D ]2} d| krÈ|
d j*| |
d j(| jd qÈW |js8|j+|
d|j,|j d n|j-r8t.|||j-|j d S ) z+Parse and check the command line arguments.ra ÚlocaleÚsphinxNrw r# z%s is not a directory.)Úfilec S s g | ]}t j|qS r )r Úabspath)r) r r r r rT s zmain.<locals>.<listcomp>r )Ú
quickstartz %s
Frn ZAuthorÚindexTzsphinx.ext.autodoczsphinx.ext.viewcodezsphinx.ext.todoÚen)r ry ÚdotÚprojectr r r r ZmasterZepubr ÚmakefileZ batchfileZ make_modeZmastertocmaxdepthZ
mastertoctreeÚlanguager r r r3 r )ZsilentÚ overwriter rx )/r§ r¦ Ú setlocaleÚLC_ALLZ init_consoler, r r$ r r¤ Ú
parse_argsr© r rb rV ry r rd rj r7 r
ÚsysÚstderrÚexitr6 r r5 r r~ r r Z
sphinx.cmdrª rc r r r r] r r Úextendr3 re Úgenerater8 r rh ) r¥ r¡ Úargsrp rQ r` Úqsrf r1 rg Údr£ r r r Úmain sx
r½ Ú__main__)r r )NN)N)r` N)N)8Ú__doc__r rk r¦ r, rµ r r Úimportlib.machineryr r Útypingr r r r Z
sphinx.localer§ r
r Zsphinx.cmd.quickstartr r
Zsphinx.util.osutilr r Zsphinx.util.templater ÚenvironrV rB Útupler r$ rF ÚstrÚboolr! r& r/ r< rJ r_ rh rR rU rt rv r~ ri r r¤ r¥ r r½ Ú__name__r r r r Ú<module>
sT
2$
*
5 a"L