diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 7ed514ed1..67ab62731 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -16,7 +16,7 @@ TERM_ENCODING = getattr(sys.stdin, 'encoding', None) from sphinx.util import make_filename from sphinx.util.console import purple, bold, red, turquoise, nocolor, color_terminal -from sphinx.util.texescape import tex_escape_map +from sphinx.util import texescape PROMPT_PREFIX = '> ' @@ -274,42 +274,36 @@ clean: \t-rm -rf %(rbuilddir)s/* html: -\tmkdir -p %(rbuilddir)s/html %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) %(rbuilddir)s/html \t@echo \t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html." pickle: -\tmkdir -p %(rbuilddir)s/pickle %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle \t@echo \t@echo "Build finished; now you can process the pickle files." json: -\tmkdir -p %(rbuilddir)s/json %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) %(rbuilddir)s/json \t@echo \t@echo "Build finished; now you can process the JSON files." htmlhelp: -\tmkdir -p %(rbuilddir)s/htmlhelp %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) %(rbuilddir)s/htmlhelp \t@echo \t@echo "Build finished; now you can run HTML Help Workshop with the" \\ \t ".hhp project file in %(rbuilddir)s/htmlhelp." qthelp: -\tmkdir -p %(rbuilddir)s/qthelp %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) %(rbuilddir)s/qthelp \t@echo \t@echo "Build finished; now you can run "qcollectiongenerator" with the" \\ \t ".qhcp project file in %(rbuilddir)s/qthelp, like this:" -\t@echo "# qcollectiongenerator %(rbuilddir)s/qthelp/Sphinx.qhcp" +\t@echo "# qcollectiongenerator %(rbuilddir)s/qthelp/%(project)s.qhcp" \t@echo "To view the help file:" \t@echo "# assistant -collectionFile %(rbuilddir)s/qthelp/%(project)s.qhc" latex: -\tmkdir -p %(rbuilddir)s/latex %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex \t@echo \t@echo "Build finished; the LaTeX files are in %(rbuilddir)s/latex." @@ -317,19 +311,115 @@ latex: \t "run these through (pdf)latex." changes: -\tmkdir -p %(rbuilddir)s/changes %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) %(rbuilddir)s/changes \t@echo \t@echo "The overview file is in %(rbuilddir)s/changes." linkcheck: -\tmkdir -p %(rbuilddir)s/linkcheck %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) %(rbuilddir)s/linkcheck \t@echo \t@echo "Link check complete; look for any errors in the above output " \\ \t "or in %(rbuilddir)s/linkcheck/output.txt." ''' +BATCHFILE = '''\ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set ALLSPHINXOPTS=-d %(rbuilddir)s/doctrees %%SPHINXOPTS%% %(rsrcdir)s +if NOT "%%PAPER%%" == "" ( +\tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%% +) + +if "%%1" == "" goto help + +if "%%1" == "help" ( +\t:help +\techo.Please use `make ^` where ^ is one of +\techo. html to make standalone HTML files +\techo. pickle to make pickle files +\techo. json to make JSON files +\techo. htmlhelp to make HTML files and a HTML help project +\techo. qthelp to make HTML files and a qthelp project +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. changes to make an overview over all changed/added/deprecated items +\techo. linkcheck to check all external links for integrity +\tgoto end +) + +if "%%1" == "clean" ( +\tfor /d %%%%i in (%(rbuilddir)s\*) do rmdir /q /s %%%%i +\tdel /q /s %(rbuilddir)s\* +\tgoto end +) + +if "%%1" == "html" ( +\t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %(rbuilddir)s/html +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/html. +\tgoto end +) + +if "%%1" == "pickle" ( +\t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle +\techo. +\techo.Build finished; now you can process the pickle files. +\tgoto end +) + +if "%%1" == "json" ( +\t%%SPHINXBUILD%% -b json %%ALLSPHINXOPTS%% %(rbuilddir)s/json +\techo. +\techo.Build finished; now you can process the JSON files. +\tgoto end +) + +if "%%1" == "htmlhelp" ( +\t%%SPHINXBUILD%% -b htmlhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/htmlhelp +\techo. +\techo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %(rbuilddir)s/htmlhelp. +\tgoto end +) + +if "%%1" == "qthelp" ( +\t%%SPHINXBUILD%% -b qthelp %%ALLSPHINXOPTS%% %(rbuilddir)s/qthelp +\techo. +\techo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %(rbuilddir)s/qthelp, like this: +\techo.^> qcollectiongenerator %(rbuilddir)s\\qthelp\\%(project)s.qhcp +\techo.To view the help file: +\techo.^> assistant -collectionFile %(rbuilddir)s\\qthelp\\%(project)s.ghc +\tgoto end +) + +if "%%1" == "latex" ( +\t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex +\techo. +\techo.Build finished; the LaTeX files are in %(rbuilddir)s/latex. +\tgoto end +) + +if "%%1" == "changes" ( +\t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %(rbuilddir)s/changes +\techo. +\techo.The overview file is in %(rbuilddir)s/changes. +\tgoto end +) + +if "%%1" == "linkcheck" ( +\t%%SPHINXBUILD%% -b linkcheck %%ALLSPHINXOPTS%% %(rbuilddir)s/linkcheck +\techo. +\techo.Link check complete; look for any errors in the above output ^ +or in %(rbuilddir)s/linkcheck/output.txt. +\tgoto end +) + +:end +''' + def mkdir_p(dir): if path.isdir(dir): @@ -391,6 +481,7 @@ def do_prompt(d, key, text, default=None, validator=nonempty): def inner_main(args): d = {} + texescape.init() if not sys.stdout.isatty() or not color_terminal(): nocolor() @@ -418,16 +509,16 @@ Enter the root path for documentation.''' 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 +Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path.''' do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n', boolean) + 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. Since the leading dot may be inconvenient for Windows users, -you can enter another prefix (such as "_") to replace the dot.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) +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.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) print ''' The project name will occur in several places in the built documentation.''' @@ -461,11 +552,11 @@ Please indicate if you want to use one of the following Sphinx extensions:''' do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx documentation ' 'of different projects (y/N)', 'n', boolean) print ''' -If you are under Unix, a Makefile can be generated for you so that you +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.''' - do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', - os.name == 'posix' and 'y' or 'n', boolean) + do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', 'y', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() @@ -474,10 +565,10 @@ directly.''' repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] - d['author_texescaped'] = unicode(d['author']).translate(tex_escape_map) + d['author_texescaped'] = unicode(d['author']).translate(texescape.tex_escape_map) d['project_doc'] = d['project'] + ' Documentation' d['project_doc_texescaped'] = \ - unicode(d['project'] + ' Documentation').translate(tex_escape_map) + unicode(d['project'] + ' Documentation').translate(texescape.tex_escape_map) if not path.isdir(d['path']): mkdir_p(d['path']) @@ -517,11 +608,19 @@ directly.''' f.write((MAKEFILE % d).encode('utf-8')) f.close() + create_batch = d['batchfile'].upper() in ('Y', 'YES') + if create_batch: + d['rsrcdir'] = separate and 'source' or '.' + d['rbuilddir'] = separate and 'build' or d['dot'] + 'build' + f = open(path.join(d['path'], 'make.bat'), 'w') + f.write((BATCHFILE % d).encode('utf-8')) + f.close() + 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 + (create_makefile and '''\ +source files. ''' % masterfile + ((create_makefile or create_batch) and '''\ Use the Makefile to build the docs, like so: make builder ''' or '''\ diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py index 4c2d0f3ec..976e2beeb 100644 --- a/tests/test_quickstart.py +++ b/tests/test_quickstart.py @@ -70,6 +70,7 @@ def test_do_prompt(): assert d['k5'] == 'no' raises(AssertionError, qs.do_prompt, d, 'k6', 'Q6', validator=qs.boolean) + @with_tempdir def test_quickstart_defaults(tempdir): answers = { @@ -86,29 +87,31 @@ def test_quickstart_defaults(tempdir): ns = {} execfile(conffile, ns) assert ns['extensions'] == [] - assert ns['templates_path'] == ['.templates'] + assert ns['templates_path'] == ['_templates'] assert ns['source_suffix'] == '.rst' assert ns['master_doc'] == 'index' assert ns['project'] == 'Sphinx Test' assert ns['copyright'] == '%s, Georg Brandl' % time.strftime('%Y') assert ns['version'] == '0.1' assert ns['release'] == '0.1' - assert ns['html_static_path'] == ['.static'] + assert ns['html_static_path'] == ['_static'] assert ns['latex_documents'] == [ ('index', 'SphinxTest.tex', 'Sphinx Test Documentation', 'Georg Brandl', 'manual')] - assert (tempdir / '.static').isdir() - assert (tempdir / '.templates').isdir() + assert (tempdir / '_static').isdir() + assert (tempdir / '_templates').isdir() assert (tempdir / 'index.rst').isfile() assert (tempdir / 'Makefile').isfile() + assert (tempdir / 'make.bat').isfile() + @with_tempdir def test_quickstart_all_answers(tempdir): answers = { 'Root path': tempdir, 'Separate source and build': 'y', - 'Name prefix for templates': '_', + 'Name prefix for templates': '.', 'Project name': 'STASI\xe2\x84\xa2', 'Author name': 'Wolfgang Sch\xc3\xa4uble & G. Beckstein', 'Project version': '2.0', @@ -119,6 +122,7 @@ def test_quickstart_all_answers(tempdir): 'doctest': 'yes', 'intersphinx': 'no', 'Create Makefile': 'no', + 'Create Windows command file': 'no', } qs.raw_input = mock_raw_input(answers, needanswer=True) qs.TERM_ENCODING = 'utf-8' @@ -129,7 +133,7 @@ def test_quickstart_all_answers(tempdir): ns = {} execfile(conffile, ns) assert ns['extensions'] == ['sphinx.ext.autodoc', 'sphinx.ext.doctest'] - assert ns['templates_path'] == ['_templates'] + assert ns['templates_path'] == ['.templates'] assert ns['source_suffix'] == '.txt' assert ns['master_doc'] == 'contents' assert ns['project'] == u'STASI™' @@ -137,12 +141,12 @@ def test_quickstart_all_answers(tempdir): time.strftime('%Y') assert ns['version'] == '2.0' assert ns['release'] == '2.0.1' - assert ns['html_static_path'] == ['_static'] + assert ns['html_static_path'] == ['.static'] assert ns['latex_documents'] == [ ('contents', 'STASI.tex', u'STASI™ Documentation', ur'Wolfgang Schäuble \& G. Beckstein', 'manual')] assert (tempdir / 'build').isdir() - assert (tempdir / 'source' / '_static').isdir() - assert (tempdir / 'source' / '_templates').isdir() + assert (tempdir / 'source' / '.static').isdir() + assert (tempdir / 'source' / '.templates').isdir() assert (tempdir / 'source' / 'contents.txt').isfile()