merge in Murkt's branch

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 ^<target^>` where ^<target^> 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"
+Inside the root directory, two more directories will be created; "_templates"
-for custom HTML templates and ".static" for custom stylesheets and other
+for custom HTML templates and "_static" for custom stylesheets and other
-static files. Since the leading dot may be inconvenient for Windows users,
+static files. You can enter another prefix (such as ".") to replace the underscore.'''
-you can enter another prefix (such as "_") to replace the dot.'''
+    do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok)
-    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)',
+    do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean)
-              os.name == 'posix' and 'y' or 'n', 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 '''\

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 / '_static').isdir()
-    assert (tempdir / '.templates').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' / '.static').isdir()
-    assert (tempdir / 'source' / '_templates').isdir()
+    assert (tempdir / 'source' / '.templates').isdir()
     assert (tempdir / 'source' / 'contents.txt').isfile()