3
T'ícâ\ ã @ s. d Z ddlZddlZddlZddlZddlZddlmZ ddlmZ ddl m
Z
m Z m Z m
Z
mZ y:ddlZej rdej krejd dZnejd d
ZW n ek
r¶ dZd
ZY nX dd lmZ ddlZdd lmZmZ dd
lmZ ddlmZm Z m Z m Z m Z ddl m!Z! ddl"m#Z# ededfdedfdedfdedfdedfded fd ed fd ed fd!ed"fd#ed$fg
Z$d%d
d&dd'd(ddd)Z%d*Z&ej'd+kr´d,Z(nd-Z(e)e)d.d/d0Z*G d1d2 d2e+Z,e)e)d3d4d5Z-e)e)d3d6d7Z.e)e)d3d8d9Z/e)e)d3d:d;Z0e)e e)ge)f d<d=d>Z1e)e2d3d?d@Z3e)e)d3dAdBZ4e)e)d3dCdDZ5de0fe)e)e e)ge
f ee)e2f dEdFdGZ6G dHdI dIe#Z7e ddJdKdLZ8dZe e2e2e)ddMdNdOZ9e e2dJdPdQZ:ej;dRdSdTZ<ej=dUd
fe
e) e>dVdWdXZ?e@dYkr*ejAe?ej=dUd
dS )[z7Quickly setup documentation source to work with Sphinx.é N)Ú OrderedDict)Úpath)ÚAnyÚCallableÚDictÚListÚUnionÚlibeditzbind ^I rl_completeTz
tab: completeF)Ú column_width)Ú__display_version__Ú package_dir)Ú__)ÚboldÚcolor_terminalÚcolorizeÚnocolorÚred)Ú ensuredir)ÚSphinxRendererZautodocz,automatically insert docstrings from modulesÚdoctestz2automatically test code snippets in doctest blocksZ intersphinxz7link between Sphinx documentation of different projectsÚtodoz9write "todo" entries that can be shown or hidden on buildZcoveragez!checks for documentation coverageZimgmathz+include math, rendered as PNG or SVG imagesZmathjaxz0include math, rendered in the browser by MathJaxÚifconfigz7conditional inclusion of content based on config valuesZviewcodez=include links to the source code of documented Python objectsZ githubpagesz=create .nojekyll file to publish the document on GitHub pagesÚ.Ú_z.rstÚindex)r ÚsepÚdotÚlanguageÚsuffixÚmasterÚmakefileÚ batchfilez> Úwin32r Zpurple)ÚpromptÚreturnc C s* t jdkr t| dd tdS t| S d S )Nr" Ú )Úend)ÚsysÚplatformÚprintÚinput)r# © r+ ú7/tmp/pip-build-gk9425m9/sphinx/sphinx/cmd/quickstart.pyÚ
term_inputD s
r- c @ s e Zd ZdZdS )ÚValidationErrorz Raised for validation errors.N)Ú__name__Ú
__module__Ú __qualname__Ú__doc__r+ r+ r+ r, r. O s r. )Úxr$ c C s$ t j| } t j| s ttd| S )Nz Please enter a valid path name.)r Ú
expanduserÚisdirr. r
)r3 r+ r+ r, Úis_pathS s
r6 c C s | dkr | S t | S )Nr% )r6 )r3 r+ r+ r, Úis_path_or_emptyZ s r7 c C s | S )Nr+ )r3 r+ r+ r, Ú allow_empty` s r8 c C s | st td| S )NzPlease enter some text.)r. r
)r3 r+ r+ r, Únonemptyd s r9 )Úlr$ c s t t d fdd }|S )N)r3 r$ c s" | kr t tddj | S )NzPlease enter one of %s.z, )r. r
Újoin)r3 )r: r+ r, Úvalk s zchoice.<locals>.val)Ústr)r: r< r+ )r: r, Úchoicej s r> c C s$ | j dkrttd| j dkS )NÚYÚYESÚNÚNOz Please enter either 'y' or 'n'.)r? r@ rA rB )r? r@ )Úupperr. r
)r3 r+ r+ r, Úbooleanr s rD c C s, | dd
dkot | dks(ttd| S )Nr é r z2Please enter a file suffix, e.g. '.rst' or '.txt'.)Úlenr. r
)r3 r+ r+ r, r x s r c C s | S )Nr+ )r3 r+ r+ r, Úok~ s rG )ÚtextÚdefaultÚ validatorr$ c C sº x´|d k r t d| |f }n t | d }tr.n"trBtt|dd}ntt|dd}t|j }|rj| rj|}y ||}W n8 tk
r® } z tt dt
| wW Y d d }~X nX P qW |S )Nz %s [%s]: z: T)Z
input_modeFz* ) Ú
PROMPT_PREFIXÚ USE_LIBEDITÚreadliner ÚCOLOR_QUESTIONr- Ústripr. r) r r= )rH rI rJ r# r3 Úerrr+ r+ r, Ú do_prompt s&
rQ c sJ e Zd Zedd fdd ZeedddZeeed fd d
Z Z S ) ÚQuickstartRendererN)Ú templatedirr$ c s |pd| _ t j d S )Nr% )rS ÚsuperÚ__init__)ÚselfrS )Ú __class__r+ r, rU s
zQuickstartRenderer.__init__)Ú
template_namer$ c C s0 t j| jt j|}| jr(t j|r(dS dS dS )z¸Check if custom template file exists.
Note: Please don't use this function from extensions.
It will be removed in the future without deprecation period.
TFN)r r; rS ÚbasenameÚexists)rV rX Útemplater+ r+ r, Ú_has_custom_template£ s z'QuickstartRenderer._has_custom_template)rX Úcontextr$ c s< | j |r*tj| jtj|}| j||S t j||S d S )N)r\ r r; rS rY Zrender_from_filerT Úrender)rV rX r] Zcustom_template)rW r+ r, r^ ¯ s
zQuickstartRenderer.render)
r/ r0 r1 r= rU Úboolr\ r r^ Ú
__classcell__r+ r+ )rW r, rR s rR )Údr$ c C s t ttdt t t td d| krNt t ttd| d n&t t td ttddt| d< xtjtj| d ds¤tjtj| d d drôt t ttd
t td t ttd d
t | d< | d svt
j d qvW d| kr&t t td ttddt | d< d| krVt t td ttddt
| d< d| krt t td ttd| d< d| krttd| d< d | krÌt t td ttd d
t| d < d | krîttd | d t| d < d!| kr2t t td" ttd#d$| d!< | d! d$kr2d%| d!< d&| krbt t td' ttd(d)t| d&< d*| krt t td+ ttd,d-| d*< xtjtj| d | d* | d& sÜtjtj| d d | d* | d& r.t t ttd.| d* | d& t td/ t ttd0| d* | d*< qW d1| kr¼t td2 g | d1< x>tj D ]2\}}td3||f dt rX| d1 jd4| qXW d5d6hj| d1 r¼t td7 | d1 jd5 d8| krìt t td9 ttd:d;t | d8< d<| kr
ttd=d;t | d<< t d%S )>a4 Ask the user for quickstart values missing from *d*.
Values are:
* path: root path
* sep: separate source and build dirs (bool)
* dot: replacement for dot in _templates etc.
* project: project name
* author: author names
* version: version of project
* release: release of project
* language: document language
* suffix: source file suffix
* master: master document name
* extensions: extensions to use (list)
* makefile: make Makefile
* batchfile: make command file
z,Welcome to the Sphinx %s quickstart utility.zyPlease enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).r zSelected root path: %sz&Enter the root path for documentation.z Root path for the documentationr zconf.pyÚsourcezDError: an existing conf.py has been found in the selected root path.z>sphinx-quickstart will not overwrite existing Sphinx projects.z4Please enter a new root path (or just Enter to exit)r% rE r zÉYou have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.z+Separate source and build directories (y/n)Únr zêInside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.z(Name prefix for templates and static dirr ÚprojectzIThe project name will occur in several places in the built documentation.z Project nameÚauthorzAuthor name(s)Úversiona- Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.zProject versionÚreleasezProject releaser a3 If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.zProject languageÚenNr zThe file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.zSource file suffixz.rstr a One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.z-Name of your master document (without suffix)r zKError: the master file %s has already been found in the selected root path.z7sphinx-quickstart will not overwrite the existing file.zIPlease enter a new file name, or rename the existing file and press EnterÚ
extensionszDIndicate which of the following Sphinx extensions should be enabled:z %s: %s (y/n)z
sphinx.ext.%szsphinx.ext.imgmathzsphinx.ext.mathjaxzZNote: imgmath and mathjax cannot be enabled at the same time. imgmath has been deselected.r zA Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.zCreate Makefile? (y/n)Úyr! z"Create Windows command file? (y/n))r) r r
r rQ r6 r Úisfiler; r7 r' ÚexitrD rG r8 r Ú
EXTENSIONSÚitemsÚappendÚissubsetÚremove)ra ÚnameÚ descriptionr+ r+ r, Úask_user· s
&&
rt )ra Ú overwriteÚsilentrS r$ c s² t |d}d krd d< d kr*d d< d d< tj d< t d d
d < jd g tjd
d d d< tjj d d< t d d r´tj
d dn d }t | d rætj
d d}d d< n:tj
| d d }t t d d ddg}dj
| d< t | t tj
| d d t tj
| d d d<t
t
t
dd fd d
}|rtjj
|d nd} | s¢tj| r´tjj
tdd d } t| }
|
j } W dQ R X |tj
|d!|j| tj
| d d" } |jd#r4d$}
ttd%|
|| |jd# n|| |jd& jd'd(kr`d)}d*}nd+}d,} d- d(krÊ d rdnd. d/< d rdn
d d d0< |tj
d d1|j| d2 d3 d(kr, d rædnd. d/< d rüdn
d d d0< |tj
d d4|j| d5 |r6dS t tttd6 t ttd7| dd8 d- sz d3 rttd9 nttd:||f ttd; t dS )=z(Generate project based on values in *d*.)rS Z
mastertoctreer% Zmastertocmaxdepthé r Zroot_docÚnowrd ú=Zproject_underlineri z%Yz, re Ú copyrightr r rb ÚbuildÚexclude_patternsr z Thumbs.dbz .DS_StoreÚ templatesÚstaticN)ÚfpathÚcontentÚnewliner$ c sl st j| rPd kr(ttd| t| dd|d}|j| W d Q R X nd krhttd| d S )NÚquietzCreating file %s.Úwtzutf-8)Úencodingr z!File %s already exists, skipping.)r rk r) r
ÚopenÚwrite)r r r Úf)ra ru r+ r, Ú
write_filee s z generate.<locals>.write_filez conf.py_tZ
quickstartzconf.pyr zquickstart/master_doc.rst_tz{A custom template `master_doc.rst_t` found. It has been renamed to `root_doc.rst_t`. Please rename it on your project too.r zquickstart/root_doc.rst_tÚ make_modeTzquickstart/Makefile.new_tzquickstart/make.bat.new_tzquickstart/Makefile_tzquickstart/make.bat_tr r ZrsrcdirZ rbuilddirÚMakefileÚ
r! zmake.batz
z:Finished: An initial directory structure has been created.zYYou should now populate your master file %s and create other documentation
source files. )r& z<Use the Makefile to build the docs, like so:
make builderzYUse the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %szPwhere "builder" is one of the supported builders, e.g. html, latex or linkcheck.)N)rR ÚtimeÚasctimer
Ú
setdefaultÚstrftimeÚosr Úabspathr r; ÚmapÚreprr= rk r r
ÚreadZ
render_stringr\ r) r r^ Úgetr r
)ra ru rv rS r[ ÚsrcdirZbuilddirr| r Z conf_pathr Z conf_textZ
masterfileÚmsgZmakefile_templateZbatchfile_templater+ )ra ru r, ÚgenerateA s
r c C s¶ | d }t j|sdS t j|s$dS ddhttj|@ r>dS | d rptj jd|}t j|sbdS t j|spdS d| d d
| d d | d | d
g}t|ttj|@ r²dS dS )Nr TFr zmake.batr rb zconf.pyr r~ r} r r )r rZ r5 Úsetr Úlistdirr; )ra ÚdirZreserved_namesr+ r+ r, Ú valid_dir¦ s(
r )r$ c C s¶ t d} tjdt d| d}|jddddd t d d
|jd d d
dt d |jddddt dd |jt d}|jdddd t dd
|jdddt d d |jd d d t d!d" |jt d#}|jd$d%d&d't d(d) |jd*d+d,d-t d.d) |jd/d0d d1t d2d3 |jd4d5d6d7t d8d) |jd9d:d;d<t d=d) |jd>d?d@t dAd" |jdBdCdDt dEd" |jdFddGt dHdI |jt dJ}x2tD ]*}|jdK| dLdM| dNt dO| dP qW |jdQdRdNdSt dTdU |jt dV}|jdWddXdYt dZd
|jd[ddXt d\d |jd]dd^dYt d_d
|jd`dd^t dad |jdbdcddddYt ded
|jdfdgdddt dhd |jt di}|jdjdkdldmt dnd) |jdodpdSdqt drds |S )tNzí
Generate required files for a Sphinx project.
sphinx-quickstart is an interactive tool that asks some questions about your
project and then generates a complete documentation directory and sample
Makefile to be used with sphinx-build.
z %(prog)s [OPTIONS] <PROJECT_DIR>z:For more information, visit <https://www.sphinx-doc.org/>.)ÚusageÚepilogrs z-qz--quietÚ
store_truer z
quiet mode)ÚactionÚdestrI Úhelpz --versionrf Z show_versionz %%(prog)s %s)r r¡ rf r Z PROJECT_DIRr ú?z project root)ÚmetavarrI Únargsr¢ zStructure optionsz--sepr z,if specified, separate source and build dirsz--no-sepÚ store_falsez/if specified, create build dir under source dir)r r¡ r¢ z--dotÚDOTr z&replacement for dot in _templates etc.)r¤ rI r¢ zProject basic optionsz-pz --projectZPROJECTrd z project name)r¤ r¡ r¢ z-az--authorZAUTHORre z author namesz-vÚVERSIONr% zversion of project)r¤ r¡ rI r¢ z-rz --releaseZRELEASErg zrelease of projectz-lz
--languageÚLANGUAGEr zdocument languagez--suffixZSUFFIXz.rstzsource file suffixz--masterZMASTERr zmaster document namez--epubFzuse epub)r rI r¢ zExtension optionsz--ext-%sÚ append_constz
sphinx.ext.%sri zenable %s extension)r Úconstr¡ r¢ z --extensionsrm ro zenable arbitrary extensions)r¤ r¡ r r¢ z Makefile and Batchfile creationz
--makefiler Tzcreate makefilez
--no-makefilezdo not create makefilez --batchfiler! zcreate batchfilez--no-batchfilezdo not create batchfilez-mz--use-make-moder z#use make-mode for Makefile/make.batz-Mz--no-use-make-modez*do not use make-mode for Makefile/make.batzProject templatingz-tz
--templatedirZ TEMPLATEDIRrS z%template directory for template filesz-dz
NAME=VALUEÚ variableszdefine a template variable)r¤ r r¡ r¢ )r
ÚargparseÚArgumentParserÚ add_argumentr Úadd_argument_grouprm )rs ÚparserÚgroupÚextr+ r+ r, Ú
get_parserà s
r´ rE )Úargvr$ c
" C s t jjtjd t jjtjjtdd t s4t
t }y|j | }W n" t
k
rj } z|jS d }~X nX t|}dd |j D }|jdg xB|d d d
D ].}d|kr¤|d j| |d j|jd q¤W y¬d|krd d
hj|sttd d S dd d
hj|rx|jd
d |jd|d
tj }|j| |}t|st tt td ttd d S nt | W n( t t fk
rª t td dS X xX|j dg D ]H}y|jd\}} | ||< W n& t!k
rþ ttd| Y nX qºW t"|d|j#d dS )Nr% ÚlocaleÚsphinxc S s i | ]\}}|d k r||qS )Nr+ )Ú.0ÚkÚvr+ r+ r, ú
<dictcomp>( s zmain.<locals>.<dictcomp>ri ú,r rd re zH"quiet" is specified, but any of "project" or "author" is not specified.rE rf rg zHError: specified path is not a directory, or sphinx files already exist.zWsphinx-quickstart only generate into a empty directory. Please specify a new root path.z[Interrupted.]é r¬ ry z Invalid template variable: %sF)ru rS r )$r· r¶ Ú setlocaleÚLC_ALLZ init_consoler r r; r r r r´ Ú
parse_argsÚ
SystemExitÚcodeÚvarsrn r rq ÚextendÚsplitrp r) r
ÚDEFAULTSÚcopyÚupdater r rt ÚKeyboardInterruptÚEOFErrorr Ú
ValueErrorr rS )
rµ r± ÚargsrP ra r³ Zd2Úvariablerr Úvaluer+ r+ r, Úmain sZ
rÏ Ú__main__)TFN)Br2 r r¶ r r' r Ú collectionsr r Útypingr r r r r rM Úparse_and_bindrL Ú ImportErrorZdocutils.utilsr
Z
sphinx.localer· r r r
Zsphinx.util.consoler r r r r Zsphinx.util.osutilr Zsphinx.util.templater rm rÆ rK r( rN r= r- Ú Exceptionr. r6 r7 r8 r9 r> r_ rD r rG rQ rR rt r r r® r´ rµ ÚintrÏ r/ rl r+ r+ r+ r, Ú<module> s
,
d U"A