179
|
1 |
# -*- coding: utf-8 -*-
|
|
2 |
"""
|
|
3 |
sphinx.quickstart
|
|
4 |
~~~~~~~~~~~~~~~~~
|
|
5 |
|
|
6 |
Quickly setup documentation source to work with Sphinx.
|
|
7 |
|
|
8 |
:copyright: 2008 by Georg Brandl.
|
|
9 |
:license: BSD.
|
|
10 |
"""
|
|
11 |
|
|
12 |
import sys, os, time
|
|
13 |
from os import path
|
|
14 |
|
|
15 |
TERM_ENCODING = getattr(sys.stdin, 'encoding', None)
|
|
16 |
|
|
17 |
from sphinx.util import make_filename
|
|
18 |
from sphinx.util.console import purple, bold, red, turquoise, nocolor, color_terminal
|
|
19 |
from sphinx.util.texescape import tex_escape_map
|
|
20 |
|
|
21 |
|
|
22 |
PROMPT_PREFIX = '> '
|
|
23 |
|
|
24 |
QUICKSTART_CONF = '''\
|
|
25 |
# -*- coding: utf-8 -*-
|
|
26 |
#
|
|
27 |
# %(project)s documentation build configuration file, created by
|
|
28 |
# sphinx-quickstart on %(now)s.
|
|
29 |
#
|
|
30 |
# This file is execfile()d with the current directory set to its containing dir.
|
|
31 |
#
|
|
32 |
# The contents of this file are pickled, so don't put values in the namespace
|
|
33 |
# that aren't pickleable (module imports are okay, they're removed automatically).
|
|
34 |
#
|
|
35 |
# Note that not all possible configuration values are present in this
|
|
36 |
# autogenerated file.
|
|
37 |
#
|
|
38 |
# All configuration values have a default; values that are commented out
|
|
39 |
# serve to show the default.
|
|
40 |
|
|
41 |
import sys, os
|
|
42 |
|
|
43 |
# If your extensions are in another directory, add it here. If the directory
|
|
44 |
# is relative to the documentation root, use os.path.abspath to make it
|
|
45 |
# absolute, like shown here.
|
|
46 |
#sys.path.append(os.path.abspath('.'))
|
|
47 |
|
|
48 |
# General configuration
|
|
49 |
# ---------------------
|
|
50 |
|
|
51 |
# Add any Sphinx extension module names here, as strings. They can be extensions
|
|
52 |
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
|
53 |
extensions = [%(extensions)s]
|
|
54 |
|
|
55 |
# Add any paths that contain templates here, relative to this directory.
|
|
56 |
templates_path = ['%(dot)stemplates']
|
|
57 |
|
|
58 |
# The suffix of source filenames.
|
|
59 |
source_suffix = '%(suffix)s'
|
|
60 |
|
|
61 |
# The encoding of source files.
|
|
62 |
#source_encoding = 'utf-8'
|
|
63 |
|
|
64 |
# The master toctree document.
|
|
65 |
master_doc = '%(master)s'
|
|
66 |
|
|
67 |
# General information about the project.
|
|
68 |
project = u'%(project)s'
|
|
69 |
copyright = u'%(copyright)s'
|
|
70 |
|
|
71 |
# The version info for the project you're documenting, acts as replacement for
|
|
72 |
# |version| and |release|, also used in various other places throughout the
|
|
73 |
# built documents.
|
|
74 |
#
|
|
75 |
# The short X.Y version.
|
|
76 |
version = '%(version)s'
|
|
77 |
# The full version, including alpha/beta/rc tags.
|
|
78 |
release = '%(release)s'
|
|
79 |
|
|
80 |
# The language for content autogenerated by Sphinx. Refer to documentation
|
|
81 |
# for a list of supported languages.
|
|
82 |
#language = None
|
|
83 |
|
|
84 |
# There are two options for replacing |today|: either, you set today to some
|
|
85 |
# non-false value, then it is used:
|
|
86 |
#today = ''
|
|
87 |
# Else, today_fmt is used as the format for a strftime call.
|
|
88 |
#today_fmt = '%%B %%d, %%Y'
|
|
89 |
|
|
90 |
# List of documents that shouldn't be included in the build.
|
|
91 |
#unused_docs = []
|
|
92 |
|
|
93 |
# List of directories, relative to source directory, that shouldn't be searched
|
|
94 |
# for source files.
|
|
95 |
exclude_trees = [%(exclude_trees)s]
|
|
96 |
|
|
97 |
# The reST default role (used for this markup: `text`) to use for all documents.
|
|
98 |
#default_role = None
|
|
99 |
|
|
100 |
# If true, '()' will be appended to :func: etc. cross-reference text.
|
|
101 |
#add_function_parentheses = True
|
|
102 |
|
|
103 |
# If true, the current module name will be prepended to all description
|
|
104 |
# unit titles (such as .. function::).
|
|
105 |
#add_module_names = True
|
|
106 |
|
|
107 |
# If true, sectionauthor and moduleauthor directives will be shown in the
|
|
108 |
# output. They are ignored by default.
|
|
109 |
#show_authors = False
|
|
110 |
|
|
111 |
# The name of the Pygments (syntax highlighting) style to use.
|
|
112 |
pygments_style = 'sphinx'
|
|
113 |
|
|
114 |
|
|
115 |
# Options for HTML output
|
|
116 |
# -----------------------
|
|
117 |
|
|
118 |
# The style sheet to use for HTML and HTML Help pages. A file of that name
|
|
119 |
# must exist either in Sphinx' static/ path, or in one of the custom paths
|
|
120 |
# given in html_static_path.
|
|
121 |
html_style = 'default.css'
|
|
122 |
|
|
123 |
# The name for this set of Sphinx documents. If None, it defaults to
|
|
124 |
# "<project> v<release> documentation".
|
|
125 |
#html_title = None
|
|
126 |
|
|
127 |
# A shorter title for the navigation bar. Default is the same as html_title.
|
|
128 |
#html_short_title = None
|
|
129 |
|
|
130 |
# The name of an image file (relative to this directory) to place at the top
|
|
131 |
# of the sidebar.
|
|
132 |
#html_logo = None
|
|
133 |
|
|
134 |
# The name of an image file (within the static path) to use as favicon of the
|
|
135 |
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
|
136 |
# pixels large.
|
|
137 |
#html_favicon = None
|
|
138 |
|
|
139 |
# Add any paths that contain custom static files (such as style sheets) here,
|
|
140 |
# relative to this directory. They are copied after the builtin static files,
|
|
141 |
# so a file named "default.css" will overwrite the builtin "default.css".
|
|
142 |
html_static_path = ['%(dot)sstatic']
|
|
143 |
|
|
144 |
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
|
145 |
# using the given strftime format.
|
|
146 |
#html_last_updated_fmt = '%%b %%d, %%Y'
|
|
147 |
|
|
148 |
# If true, SmartyPants will be used to convert quotes and dashes to
|
|
149 |
# typographically correct entities.
|
|
150 |
#html_use_smartypants = True
|
|
151 |
|
|
152 |
# Custom sidebar templates, maps document names to template names.
|
|
153 |
#html_sidebars = {}
|
|
154 |
|
|
155 |
# Additional templates that should be rendered to pages, maps page names to
|
|
156 |
# template names.
|
|
157 |
#html_additional_pages = {}
|
|
158 |
|
|
159 |
# If false, no module index is generated.
|
|
160 |
#html_use_modindex = True
|
|
161 |
|
|
162 |
# If false, no index is generated.
|
|
163 |
#html_use_index = True
|
|
164 |
|
|
165 |
# If true, the index is split into individual pages for each letter.
|
|
166 |
#html_split_index = False
|
|
167 |
|
|
168 |
# If true, the reST sources are included in the HTML build as _sources/<name>.
|
|
169 |
#html_copy_source = True
|
|
170 |
|
|
171 |
# If true, an OpenSearch description file will be output, and all pages will
|
|
172 |
# contain a <link> tag referring to it. The value of this option must be the
|
|
173 |
# base URL from which the finished HTML is served.
|
|
174 |
#html_use_opensearch = ''
|
|
175 |
|
|
176 |
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
|
177 |
#html_file_suffix = ''
|
|
178 |
|
|
179 |
# Output file base name for HTML help builder.
|
|
180 |
htmlhelp_basename = '%(project_fn)sdoc'
|
|
181 |
|
|
182 |
|
|
183 |
# Options for LaTeX output
|
|
184 |
# ------------------------
|
|
185 |
|
|
186 |
# The paper size ('letter' or 'a4').
|
|
187 |
#latex_paper_size = 'letter'
|
|
188 |
|
|
189 |
# The font size ('10pt', '11pt' or '12pt').
|
|
190 |
#latex_font_size = '10pt'
|
|
191 |
|
|
192 |
# Grouping the document tree into LaTeX files. List of tuples
|
|
193 |
# (source start file, target name, title, author, document class [howto/manual]).
|
|
194 |
latex_documents = [
|
|
195 |
('%(master)s', '%(project_fn)s.tex', ur'%(project_doc_texescaped)s',
|
|
196 |
ur'%(author_texescaped)s', 'manual'),
|
|
197 |
]
|
|
198 |
|
|
199 |
# The name of an image file (relative to this directory) to place at the top of
|
|
200 |
# the title page.
|
|
201 |
#latex_logo = None
|
|
202 |
|
|
203 |
# For "manual" documents, if this is true, then toplevel headings are parts,
|
|
204 |
# not chapters.
|
|
205 |
#latex_use_parts = False
|
|
206 |
|
|
207 |
# Additional stuff for the LaTeX preamble.
|
|
208 |
#latex_preamble = ''
|
|
209 |
|
|
210 |
# Documents to append as an appendix to all manuals.
|
|
211 |
#latex_appendices = []
|
|
212 |
|
|
213 |
# If false, no module index is generated.
|
|
214 |
#latex_use_modindex = True
|
|
215 |
'''
|
|
216 |
|
|
217 |
INTERSPHINX_CONFIG = '''
|
|
218 |
|
|
219 |
# Example configuration for intersphinx: refer to the Python standard library.
|
|
220 |
intersphinx_mapping = {'http://docs.python.org/dev': None}
|
|
221 |
'''
|
|
222 |
|
|
223 |
MASTER_FILE = '''\
|
|
224 |
.. %(project)s documentation master file, created by sphinx-quickstart on %(now)s.
|
|
225 |
You can adapt this file completely to your liking, but it should at least
|
|
226 |
contain the root `toctree` directive.
|
|
227 |
|
|
228 |
Welcome to %(project)s's documentation!
|
|
229 |
===========%(underline)s=================
|
|
230 |
|
|
231 |
Contents:
|
|
232 |
|
|
233 |
.. toctree::
|
|
234 |
:maxdepth: 2
|
|
235 |
|
|
236 |
Indices and tables
|
|
237 |
==================
|
|
238 |
|
|
239 |
* :ref:`genindex`
|
|
240 |
* :ref:`modindex`
|
|
241 |
* :ref:`search`
|
|
242 |
|
|
243 |
'''
|
|
244 |
|
|
245 |
MAKEFILE = '''\
|
|
246 |
# Makefile for Sphinx documentation
|
|
247 |
#
|
|
248 |
|
|
249 |
# You can set these variables from the command line.
|
|
250 |
SPHINXOPTS =
|
|
251 |
SPHINXBUILD = sphinx-build
|
|
252 |
PAPER =
|
|
253 |
|
|
254 |
# Internal variables.
|
|
255 |
PAPEROPT_a4 = -D latex_paper_size=a4
|
|
256 |
PAPEROPT_letter = -D latex_paper_size=letter
|
|
257 |
ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \
|
|
258 |
$(SPHINXOPTS) %(rsrcdir)s
|
|
259 |
|
|
260 |
.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
|
|
261 |
|
|
262 |
help:
|
|
263 |
\t@echo "Please use \\`make <target>' where <target> is one of"
|
|
264 |
\t@echo " html to make standalone HTML files"
|
|
265 |
\t@echo " pickle to make pickle files"
|
|
266 |
\t@echo " json to make JSON files"
|
|
267 |
\t@echo " htmlhelp to make HTML files and a HTML help project"
|
|
268 |
\t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
|
269 |
\t@echo " changes to make an overview over all changed/added/deprecated items"
|
|
270 |
\t@echo " linkcheck to check all external links for integrity"
|
|
271 |
|
|
272 |
clean:
|
|
273 |
\t-rm -rf %(rbuilddir)s/*
|
|
274 |
|
|
275 |
html:
|
|
276 |
\tmkdir -p %(rbuilddir)s/html %(rbuilddir)s/doctrees
|
|
277 |
\t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) %(rbuilddir)s/html
|
|
278 |
\t@echo
|
|
279 |
\t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html."
|
|
280 |
|
|
281 |
pickle:
|
|
282 |
\tmkdir -p %(rbuilddir)s/pickle %(rbuilddir)s/doctrees
|
|
283 |
\t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle
|
|
284 |
\t@echo
|
|
285 |
\t@echo "Build finished; now you can process the pickle files."
|
|
286 |
|
|
287 |
web: pickle
|
|
288 |
|
|
289 |
json:
|
|
290 |
\tmkdir -p %(rbuilddir)s/json %(rbuilddir)s/doctrees
|
|
291 |
\t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) %(rbuilddir)s/json
|
|
292 |
\t@echo
|
|
293 |
\t@echo "Build finished; now you can process the JSON files."
|
|
294 |
|
|
295 |
htmlhelp:
|
|
296 |
\tmkdir -p %(rbuilddir)s/htmlhelp %(rbuilddir)s/doctrees
|
|
297 |
\t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) %(rbuilddir)s/htmlhelp
|
|
298 |
\t@echo
|
|
299 |
\t@echo "Build finished; now you can run HTML Help Workshop with the" \\
|
|
300 |
\t ".hhp project file in %(rbuilddir)s/htmlhelp."
|
|
301 |
|
|
302 |
latex:
|
|
303 |
\tmkdir -p %(rbuilddir)s/latex %(rbuilddir)s/doctrees
|
|
304 |
\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex
|
|
305 |
\t@echo
|
|
306 |
\t@echo "Build finished; the LaTeX files are in %(rbuilddir)s/latex."
|
|
307 |
\t@echo "Run \\`make all-pdf' or \\`make all-ps' in that directory to" \\
|
|
308 |
\t "run these through (pdf)latex."
|
|
309 |
|
|
310 |
changes:
|
|
311 |
\tmkdir -p %(rbuilddir)s/changes %(rbuilddir)s/doctrees
|
|
312 |
\t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) %(rbuilddir)s/changes
|
|
313 |
\t@echo
|
|
314 |
\t@echo "The overview file is in %(rbuilddir)s/changes."
|
|
315 |
|
|
316 |
linkcheck:
|
|
317 |
\tmkdir -p %(rbuilddir)s/linkcheck %(rbuilddir)s/doctrees
|
|
318 |
\t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) %(rbuilddir)s/linkcheck
|
|
319 |
\t@echo
|
|
320 |
\t@echo "Link check complete; look for any errors in the above output " \\
|
|
321 |
\t "or in %(rbuilddir)s/linkcheck/output.txt."
|
|
322 |
'''
|
|
323 |
|
|
324 |
|
|
325 |
def mkdir_p(dir):
|
|
326 |
if path.isdir(dir):
|
|
327 |
return
|
|
328 |
os.makedirs(dir)
|
|
329 |
|
|
330 |
|
|
331 |
def is_path(x):
|
|
332 |
"""Please enter a valid path name."""
|
|
333 |
return path.isdir(x) or not path.exists(x)
|
|
334 |
|
|
335 |
def nonempty(x):
|
|
336 |
"""Please enter some text."""
|
|
337 |
return len(x)
|
|
338 |
|
|
339 |
def choice(*l):
|
|
340 |
def val(x):
|
|
341 |
return x in l
|
|
342 |
val.__doc__ = 'Please enter one of %s.' % ', '.join(l)
|
|
343 |
return val
|
|
344 |
|
|
345 |
def boolean(x):
|
|
346 |
"""Please enter either 'y' or 'n'."""
|
|
347 |
return x.upper() in ('Y', 'YES', 'N', 'NO')
|
|
348 |
|
|
349 |
def suffix(x):
|
|
350 |
"""Please enter a file suffix, e.g. '.rst' or '.txt'."""
|
|
351 |
return x[0:1] == '.' and len(x) > 1
|
|
352 |
|
|
353 |
def ok(x):
|
|
354 |
return True
|
|
355 |
|
|
356 |
|
|
357 |
def do_prompt(d, key, text, default=None, validator=nonempty):
|
|
358 |
while True:
|
|
359 |
if default:
|
|
360 |
prompt = purple(PROMPT_PREFIX + '%s [%s]: ' % (text, default))
|
|
361 |
else:
|
|
362 |
prompt = purple(PROMPT_PREFIX + text + ': ')
|
|
363 |
x = raw_input(prompt)
|
|
364 |
if default and not x:
|
|
365 |
x = default
|
|
366 |
if x.decode('ascii', 'replace').encode('ascii', 'replace') != x:
|
|
367 |
if TERM_ENCODING:
|
|
368 |
x = x.decode(TERM_ENCODING)
|
|
369 |
else:
|
|
370 |
print turquoise('* Note: non-ASCII characters entered and terminal '
|
|
371 |
'encoding unknown -- assuming UTF-8 or Latin-1.')
|
|
372 |
try:
|
|
373 |
x = x.decode('utf-8')
|
|
374 |
except UnicodeDecodeError:
|
|
375 |
x = x.decode('latin1')
|
|
376 |
if validator and not validator(x):
|
|
377 |
print red('* ' + validator.__doc__)
|
|
378 |
continue
|
|
379 |
break
|
|
380 |
d[key] = x
|
|
381 |
|
|
382 |
|
|
383 |
def inner_main(args):
|
|
384 |
d = {}
|
|
385 |
|
|
386 |
if not sys.stdout.isatty() or not color_terminal():
|
|
387 |
nocolor()
|
|
388 |
|
|
389 |
print bold('Welcome to the Sphinx quickstart utility.')
|
|
390 |
print '''
|
|
391 |
Please enter values for the following settings (just press Enter to
|
|
392 |
accept a default value, if one is given in brackets).'''
|
|
393 |
|
|
394 |
print '''
|
|
395 |
Enter the root path for documentation.'''
|
|
396 |
do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
|
|
397 |
|
|
398 |
while path.isfile(path.join(d['path'], 'conf.py')) or \
|
|
399 |
path.isfile(path.join(d['path'], 'source', 'conf.py')):
|
|
400 |
print
|
|
401 |
print bold('Error: an existing conf.py has been found in the '
|
|
402 |
'selected root path.')
|
|
403 |
print 'sphinx-quickstart will not overwrite existing Sphinx projects.'
|
|
404 |
print
|
|
405 |
do_prompt(d, 'path', 'Please enter a new root path (or just Enter to exit)',
|
|
406 |
'', is_path)
|
|
407 |
if not d['path']:
|
|
408 |
sys.exit(1)
|
|
409 |
|
|
410 |
print '''
|
|
411 |
You have two options for placing the build directory for Sphinx output.
|
|
412 |
Either, you use a directory ".build" within the root path, or you separate
|
|
413 |
"source" and "build" directories within the root path.'''
|
|
414 |
do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n',
|
|
415 |
boolean)
|
|
416 |
print '''
|
|
417 |
Inside the root directory, two more directories will be created; ".templates"
|
|
418 |
for custom HTML templates and ".static" for custom stylesheets and other
|
|
419 |
static files. Since the leading dot may be inconvenient for Windows users,
|
|
420 |
you can enter another prefix (such as "_") to replace the dot.'''
|
|
421 |
do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok)
|
|
422 |
|
|
423 |
print '''
|
|
424 |
The project name will occur in several places in the built documentation.'''
|
|
425 |
do_prompt(d, 'project', 'Project name')
|
|
426 |
do_prompt(d, 'author', 'Author name(s)')
|
|
427 |
print '''
|
|
428 |
Sphinx has the notion of a "version" and a "release" for the
|
|
429 |
software. Each version can have multiple releases. For example, for
|
|
430 |
Python the version is something like 2.5 or 3.0, while the release is
|
|
431 |
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
|
|
432 |
just set both to the same value.'''
|
|
433 |
do_prompt(d, 'version', 'Project version')
|
|
434 |
do_prompt(d, 'release', 'Project release', d['version'])
|
|
435 |
print '''
|
|
436 |
The file name suffix for source files. Commonly, this is either ".txt"
|
|
437 |
or ".rst". Only files with this suffix are considered documents.'''
|
|
438 |
do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix)
|
|
439 |
print '''
|
|
440 |
One document is special in that it is considered the top node of the
|
|
441 |
"contents tree", that is, it is the root of the hierarchical structure
|
|
442 |
of the documents. Normally, this is "index", but if your "index"
|
|
443 |
document is a custom template, you can also set this to another filename.'''
|
|
444 |
do_prompt(d, 'master', 'Name of your master document (without suffix)',
|
|
445 |
'index')
|
|
446 |
print '''
|
|
447 |
Please indicate if you want to use one of the following Sphinx extensions:'''
|
|
448 |
do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings '
|
|
449 |
'from modules (y/N)', 'n', boolean)
|
|
450 |
do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets '
|
|
451 |
'in doctest blocks (y/N)', 'n', boolean)
|
|
452 |
do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx documentation '
|
|
453 |
'of different projects (y/N)', 'n', boolean)
|
|
454 |
print '''
|
|
455 |
If you are under Unix, a Makefile can be generated for you so that you
|
|
456 |
only have to run e.g. `make html' instead of invoking sphinx-build
|
|
457 |
directly.'''
|
|
458 |
do_prompt(d, 'makefile', 'Create Makefile? (Y/n)',
|
|
459 |
os.name == 'posix' and 'y' or 'n', boolean)
|
|
460 |
|
|
461 |
d['project_fn'] = make_filename(d['project'])
|
|
462 |
d['now'] = time.asctime()
|
|
463 |
d['underline'] = len(d['project']) * '='
|
|
464 |
d['extensions'] = ', '.join(
|
|
465 |
repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx')
|
|
466 |
if d['ext_' + name].upper() in ('Y', 'YES'))
|
|
467 |
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
|
|
468 |
d['author_texescaped'] = unicode(d['author']).translate(tex_escape_map)
|
|
469 |
d['project_doc'] = d['project'] + ' Documentation'
|
|
470 |
d['project_doc_texescaped'] = \
|
|
471 |
unicode(d['project'] + ' Documentation').translate(tex_escape_map)
|
|
472 |
|
|
473 |
if not path.isdir(d['path']):
|
|
474 |
mkdir_p(d['path'])
|
|
475 |
|
|
476 |
separate = d['sep'].upper() in ('Y', 'YES')
|
|
477 |
srcdir = separate and path.join(d['path'], 'source') or d['path']
|
|
478 |
|
|
479 |
mkdir_p(srcdir)
|
|
480 |
if separate:
|
|
481 |
builddir = path.join(d['path'], 'build')
|
|
482 |
d['exclude_trees'] = ''
|
|
483 |
else:
|
|
484 |
builddir = path.join(srcdir, d['dot'] + 'build')
|
|
485 |
d['exclude_trees'] = repr(d['dot'] + 'build')
|
|
486 |
mkdir_p(builddir)
|
|
487 |
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
|
|
488 |
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
|
|
489 |
|
|
490 |
conf_text = QUICKSTART_CONF % d
|
|
491 |
if d['ext_intersphinx'].upper() in ('Y', 'YES'):
|
|
492 |
conf_text += INTERSPHINX_CONFIG
|
|
493 |
|
|
494 |
f = open(path.join(srcdir, 'conf.py'), 'w')
|
|
495 |
f.write(conf_text.encode('utf-8'))
|
|
496 |
f.close()
|
|
497 |
|
|
498 |
masterfile = path.join(srcdir, d['master'] + d['suffix'])
|
|
499 |
f = open(masterfile, 'w')
|
|
500 |
f.write((MASTER_FILE % d).encode('utf-8'))
|
|
501 |
f.close()
|
|
502 |
|
|
503 |
create_makefile = d['makefile'].upper() in ('Y', 'YES')
|
|
504 |
if create_makefile:
|
|
505 |
d['rsrcdir'] = separate and 'source' or '.'
|
|
506 |
d['rbuilddir'] = separate and 'build' or d['dot'] + 'build'
|
|
507 |
f = open(path.join(d['path'], 'Makefile'), 'w')
|
|
508 |
f.write((MAKEFILE % d).encode('utf-8'))
|
|
509 |
f.close()
|
|
510 |
|
|
511 |
print
|
|
512 |
print bold('Finished: An initial directory structure has been created.')
|
|
513 |
print '''
|
|
514 |
You should now populate your master file %s and create other documentation
|
|
515 |
source files. ''' % masterfile + (create_makefile and '''\
|
|
516 |
Use the Makefile to build the docs, like so:
|
|
517 |
make builder
|
|
518 |
''' or '''\
|
|
519 |
Use the sphinx-build command to build the docs, like so:
|
|
520 |
sphinx-build -b builder %s %s
|
|
521 |
''' % (srcdir, builddir)) + '''\
|
|
522 |
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
|
|
523 |
'''
|
|
524 |
|
|
525 |
|
|
526 |
def main(argv=sys.argv):
|
|
527 |
try:
|
|
528 |
return inner_main(argv)
|
|
529 |
except (KeyboardInterrupt, EOFError):
|
|
530 |
print
|
|
531 |
print '[Interrupted.]'
|
|
532 |
return
|
|
533 |
|