diff options
Diffstat (limited to 'sphinx/quickstart.py')
| -rw-r--r-- | sphinx/quickstart.py | 173 |
1 files changed, 116 insertions, 57 deletions
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 5cf067e9..e480923d 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -8,12 +8,24 @@ :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ +from __future__ import print_function import sys, os, time, re from os import path +from io import open TERM_ENCODING = getattr(sys.stdin, 'encoding', None) +#try to import readline, unix specific enhancement +try: + import readline + if readline.__doc__ and 'libedit' in readline.__doc__: + readline.parse_and_bind("bind ^I rl_complete") + else: + readline.parse_and_bind("tab: complete") +except ImportError: + pass + from docutils.utils import column_width from sphinx import __version__ @@ -21,7 +33,6 @@ from sphinx.util.osutil import make_filename from sphinx.util.console import purple, bold, red, turquoise, \ nocolor, color_terminal from sphinx.util import texescape -from sphinx.util.pycompat import open # function to get input from terminal -- overridden by the test suite try: @@ -99,7 +110,10 @@ release = '%(release_str)s' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = %(language)r # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -217,10 +231,23 @@ html_static_path = ['%(dot)sstatic'] # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + # Output file base name for HTML help builder. htmlhelp_basename = '%(project_fn)sdoc' - # -- Options for LaTeX output --------------------------------------------- latex_elements = { @@ -232,6 +259,9 @@ latex_elements = { # Additional stuff for the LaTeX preamble. #'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples @@ -320,7 +350,7 @@ epub_copyright = u'%(copyright_str)s' #epub_theme = 'epub' # The language of the text. It defaults to the language option -# or en if the language is not set. +# or 'en' if the language is not set. #epub_language = '' # The scheme of the identifier. Typical schemes are ISBN or URL. @@ -642,6 +672,14 @@ if "%%1" == "clean" ( ) +REM Check if sphinx-build is available and fallback to Python version if any +%%SPHINXBUILD%% 2> nul +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ %%SPHINXBUILD%% 2> nul if errorlevel 9009 ( \techo. @@ -655,6 +693,9 @@ if errorlevel 9009 ( \texit /b 1 ) +:sphinx_ok + + if "%%1" == "html" ( \t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %%BUILDDIR%%/html \tif errorlevel 1 exit /b 1 @@ -918,6 +959,7 @@ class ValidationError(Exception): """Raised for validation errors.""" def is_path(x): + x = path.expanduser(x) if path.exists(x) and not path.isdir(x): raise ValidationError("Please enter a valid path name.") return x @@ -962,9 +1004,9 @@ def do_prompt(d, key, text, default=None, validator=nonempty): if TERM_ENCODING: prompt = prompt.encode(TERM_ENCODING) else: - print turquoise('* Note: non-ASCII default value provided ' + print(turquoise('* Note: non-ASCII default value provided ' 'and terminal encoding unknown -- assuming ' - 'UTF-8 or Latin-1.') + 'UTF-8 or Latin-1.')) try: prompt = prompt.encode('utf-8') except UnicodeEncodeError: @@ -979,17 +1021,17 @@ def do_prompt(d, key, text, default=None, validator=nonempty): if TERM_ENCODING: x = x.decode(TERM_ENCODING) else: - print turquoise('* Note: non-ASCII characters entered ' + print(turquoise('* Note: non-ASCII characters entered ' 'and terminal encoding unknown -- assuming ' - 'UTF-8 or Latin-1.') + 'UTF-8 or Latin-1.')) try: x = x.decode('utf-8') except UnicodeDecodeError: x = x.decode('latin1') try: x = validator(x) - except ValidationError, err: - print red('* ' + str(err)) + except ValidationError as err: + print(red('* ' + str(err))) continue break d[key] = x @@ -1018,6 +1060,7 @@ def ask_user(d): * author: author names * version: version of project * release: release of project + * language: document language * suffix: source file suffix * master: master document name * epub: use epub (bool) @@ -1026,98 +1069,110 @@ def ask_user(d): * batchfile: make command file """ - print bold('Welcome to the Sphinx %s quickstart utility.') % __version__ - print ''' + print(bold('Welcome to the Sphinx %s quickstart utility.') % __version__) + print(''' Please enter values for the following settings (just press Enter to -accept a default value, if one is given in brackets).''' +accept a default value, if one is given in brackets).''') if 'path' in d: - print bold(''' -Selected root path: %s''' % d['path']) + print(bold(''' +Selected root path: %s''' % d['path'])) else: - print ''' -Enter the root path for documentation.''' + print(''' +Enter the root path for documentation.''') do_prompt(d, 'path', 'Root path for the documentation', '.', is_path) while path.isfile(path.join(d['path'], 'conf.py')) or \ path.isfile(path.join(d['path'], 'source', 'conf.py')): - print - print bold('Error: an existing conf.py has been found in the ' - 'selected root path.') - print 'sphinx-quickstart will not overwrite existing Sphinx projects.' - print + print() + print(bold('Error: an existing conf.py has been found in the ' + 'selected root path.')) + print('sphinx-quickstart will not overwrite existing Sphinx projects.') + print() do_prompt(d, 'path', 'Please enter a new root path (or just Enter ' 'to exit)', '', is_path) if not d['path']: sys.exit(1) if 'sep' not in d: - print ''' + print(''' 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.''' +"source" and "build" directories within the root path.''') do_prompt(d, 'sep', 'Separate source and build directories (y/n)', 'n', boolean) if 'dot' not in d: - print ''' + print(''' 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.''' +files. You can enter another prefix (such as ".") to replace the underscore.''') do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) if 'project' not in d: - print ''' -The project name will occur in several places in the built documentation.''' + print(''' +The project name will occur in several places in the built documentation.''') do_prompt(d, 'project', 'Project name') if 'author' not in d: do_prompt(d, 'author', 'Author name(s)') if 'version' not in d: - print ''' + print(''' 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.''' +just set both to the same value.''') do_prompt(d, 'version', 'Project version') if 'release' not in d: do_prompt(d, 'release', 'Project release', d['version']) + if 'language' not in d: + print(''' +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 +http://sphinx-doc.org/config.html#confval-language.''') + do_prompt(d, 'language', 'Project language', 'en') + if d['language'] == 'en': + d['language'] = None + if 'suffix' not in d: - print ''' + print(''' The file name suffix for source files. Commonly, this is either ".txt" -or ".rst". Only files with this suffix are considered documents.''' +or ".rst". Only files with this suffix are considered documents.''') do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix) if 'master' not in d: - print ''' + print(''' 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.''' +document is a custom template, you can also set this to another filename.''') do_prompt(d, 'master', 'Name of your master document (without suffix)', 'index') while path.isfile(path.join(d['path'], d['master']+d['suffix'])) or \ path.isfile(path.join(d['path'], 'source', d['master']+d['suffix'])): - print - print bold('Error: the master file %s has already been found in the ' - 'selected root path.' % (d['master']+d['suffix'])) - print 'sphinx-quickstart will not overwrite the existing file.' - print + print() + print(bold('Error: the master file %s has already been found in the ' + 'selected root path.' % (d['master']+d['suffix']))) + print('sphinx-quickstart will not overwrite the existing file.') + print() do_prompt(d, 'master', 'Please enter a new file name, or rename the ' 'existing file and press Enter', d['master']) if 'epub' not in d: - print ''' -Sphinx can also add configuration for epub output:''' + print(''' +Sphinx can also add configuration for epub output:''') do_prompt(d, 'epub', 'Do you want to use the epub builder (y/n)', 'n', boolean) if 'ext_autodoc' not in d: - print ''' -Please indicate if you want to use one of the following Sphinx extensions:''' + print(''' +Please indicate if you want to use one of the following Sphinx extensions:''') do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings ' 'from modules (y/n)', 'n', boolean) if 'ext_doctest' not in d: @@ -1139,8 +1194,8 @@ Please indicate if you want to use one of the following Sphinx extensions:''' do_prompt(d, 'ext_mathjax', 'mathjax: include math, rendered in the ' 'browser by MathJax (y/n)', 'n', boolean) if d['ext_pngmath'] and d['ext_mathjax']: - print '''Note: pngmath and mathjax cannot be enabled at the same time. -pngmath has been deselected.''' + print('''Note: pngmath and mathjax cannot be enabled at the same time. +pngmath has been deselected.''') d['ext_pngmath'] = False if 'ext_ifconfig' not in d: do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of ' @@ -1150,15 +1205,15 @@ pngmath has been deselected.''' 'code of documented Python objects (y/n)', 'n', boolean) if 'makefile' not in d: - print ''' + print(''' A 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.''' +directly.''') do_prompt(d, 'makefile', 'Create Makefile? (y/n)', 'y', boolean) if 'batchfile' not in d: do_prompt(d, 'batchfile', 'Create Windows command file? (y/n)', 'y', boolean) - print + print() def generate(d, overwrite=True, silent=False): @@ -1217,14 +1272,14 @@ def generate(d, overwrite=True, silent=False): def write_file(fpath, content, newline=None): if overwrite or not path.isfile(fpath): - print 'Creating file %s.' % fpath + print('Creating file %s.' % fpath) f = open(fpath, 'wt', encoding='utf-8', newline=newline) try: f.write(content) finally: f.close() else: - print 'File %s already exists, skipping.' % fpath + print('File %s already exists, skipping.' % fpath) conf_text = QUICKSTART_CONF % d if d['epub']: @@ -1250,9 +1305,9 @@ def generate(d, overwrite=True, silent=False): if silent: return - print - print bold('Finished: An initial directory structure has been created.') - print ''' + print() + print(bold('Finished: An initial directory structure has been created.')) + print(''' You should now populate your master file %s and create other documentation source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\ Use the Makefile to build the docs, like so: @@ -1262,7 +1317,7 @@ Use the sphinx-build command to build the docs, like so: sphinx-build -b builder %s %s ''' % (srcdir, builddir)) + '''\ where "builder" is one of the supported builders, e.g. html, latex or linkcheck. -''' +''') def main(argv=sys.argv): @@ -1271,14 +1326,18 @@ def main(argv=sys.argv): d = {} if len(argv) > 3: - print 'Usage: sphinx-quickstart [root]' + print('Usage: sphinx-quickstart [root]') sys.exit(1) elif len(argv) == 2: d['path'] = argv[1] try: ask_user(d) except (KeyboardInterrupt, EOFError): - print - print '[Interrupted.]' + print() + print('[Interrupted.]') return generate(d) + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) |