merge

CHANGES

@@ -93,6 +93,8 @@ Features added
   catalog output / applying translation catalog to generated documentation.
 * #1583: Allow the line numbering of the directive `literalinclude` to match
   that of the included file, using a new ``lineno-match`` option.
+* PR#299: add various options to sphinx-quickstart. Quiet mode option
+  ``--quiet`` will skips wizard mode. Thanks to WAKAYAMA shirou.
 
 Bugs fixed
 ----------
@@ -159,6 +161,7 @@ Bugs fixed
   directory. Thanks to Peter Suter.
 * PR#297, #1571: Add imgpath property to all builders. It make easier to
   develop builder extensions. Thanks to Takeshi Komiya.
+* #1584: Point to master doc in HTML "top" link.
 
 Documentation
 -------------

doc/invocation.rst

@@ -1,5 +1,138 @@
+.. default-role:: any
+
 .. _invocation:
 
+Invocation of sphinx-quickstart
+===============================
+
+The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
+It is called like this::
+
+     $ sphinx-quickstart [options] [projectdir]
+
+where *projectdir* is the Sphinx documentation set directory in which you want
+to place. If you omit *projectdir*, files are generated into current directory
+by default.
+
+The :program:`sphinx-quickstart` script has several options:
+
+.. program:: sphinx-quickstart
+
+.. option:: -q, --quiet
+
+   Quiet mode that will skips interactive wizard to specify options.
+   This option requires `-p`, `-a` and `-v` options.
+
+.. option:: -h, --help, --version
+
+   Display usage summary or Sphinx version.
+
+
+Structure options
+-----------------
+
+.. option:: --sep
+
+   If specified, separate source and build directories.
+
+.. option:: --dot=DOT
+
+   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.
+
+Project basic options
+---------------------
+
+.. option:: -p PROJECT, --project=PROJECT
+
+   Project name will be set. (see :confval:`project`).
+
+.. option:: -a AUTHOR, --author=AUTHOR
+
+   Author names. (see :confval:`copyright`).
+
+.. option:: -v VERSION
+
+   Version of project. (see :confval:`version`).
+
+.. option:: -r RELEASE, --release=RELEASE
+
+   Release of project. (see :confval:`release`).
+
+.. option:: -l LANGUAGE, --language=LANGUAGE
+
+   Document language. (see :confval:`language`).
+
+.. option:: --suffix=SUFFIX
+
+   Source file suffix. (see :confval:`source_suffix`).
+
+.. option:: --master=MASTER
+
+   Master document name. (see :confval:`master_doc`).
+
+.. option:: --epub
+
+   Use epub.
+
+Extension options
+-----------------
+
+.. option:: --ext-autodoc
+
+   Enable `sphinx.ext.autodoc` extension.
+
+.. option:: --ext-doctest
+
+   Enable `sphinx.ext.doctest` extension.
+
+.. option:: --ext-intersphinx
+
+   Enable `sphinx.ext.intersphinx` extension.
+
+.. option:: --ext-todo
+
+   Enable `sphinx.ext.todo` extension.
+
+.. option:: --ext-coverage
+
+   Enable `sphinx.ext.coverage` extension.
+
+.. option:: --ext-pngmath
+
+   Enable `sphinx.ext.pngmath` extension.
+
+.. option:: --ext-mathjax
+
+   Enable `sphinx.ext.mathjax` extension.
+
+.. option:: --ext-ifconfig
+
+   Enable `sphinx.ext.ifconfig` extension.
+
+.. option:: --ext-viewcode
+
+   Enable `sphinx.ext.viewcode` extension.
+
+
+Makefile and Batchfile creation options
+---------------------------------------
+
+.. option:: --makefile, --no-makefile
+
+   Create (or not create) makefile.
+
+.. option:: --batchfile, --no-batchfile
+
+   Create (or not create) batchfile
+
+
+.. versionadded:: 1.3
+   Add various options for sphinx-quickstart invocation.
+
+
 Invocation of sphinx-build
 ==========================
 

sphinx/builders/__init__.py

@@ -71,9 +71,9 @@ class Builder(object):
         # images that need to be copied over (source -> dest)
         self.images = {}
         # basename of images directory
-        imagedir = ""
+        self.imagedir = ""
         # relative path to image directory from current docname (used at writing docs)
-        imgpath = ""
+        self.imgpath = ""
 
         # these get set later
         self.parallel_ok = False

sphinx/directives/code.py

@@ -63,11 +63,14 @@ def dedent_lines(lines, dedent):
 
 
 def container_wrapper(directive, literal_node, caption):
-    caption_node = nodes.caption()
-    directive.state.nested_parse(ViewList([caption], source=''),
-                                 directive.content_offset, caption_node)
-
     container_node = nodes.container('', literal_block=True)
+    parsed = nodes.Element()
+    directive.state.nested_parse(ViewList([caption], source=''),
+                                 directive.content_offset, parsed)
+    caption_node = nodes.caption(parsed[0].rawsource, '',
+                                 *parsed[0].children)
+    caption_node.source = parsed[0].source
+    caption_node.line = parsed[0].line
     container_node += caption_node
     container_node += literal_node
     return container_node

sphinx/quickstart.py

@@ -13,6 +13,7 @@ from __future__ import print_function
 import re
 import os
 import sys
+import optparse
 import time
 from os import path
 from io import open
@@ -42,6 +43,22 @@ from sphinx.util import texescape
 # function to get input from terminal -- overridden by the test suite
 term_input = input
 
+DEFAULT_VALUE = {
+    'path': '.',
+    'sep': False,
+    'dot': '_',
+    'language': None,
+    'suffix': '.rst',
+    'master': 'index',
+    'epub': False,
+    'ext_autodoc': False,
+    'ext_doctest': False,
+    'makefile': True,
+    'batchfile': True,
+    }
+
+EXTENSIONS = ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
+              'pngmath', 'mathjax', 'ifconfig', 'viewcode')
 
 PROMPT_PREFIX = '> '
 
@@ -1228,13 +1245,17 @@ pngmath has been deselected.''')
         do_prompt(d, 'ext_viewcode', 'viewcode: include links to the source '
                   'code of documented Python objects (y/n)', 'n', boolean)
 
-    if 'makefile' not in d:
+    if 'no_makefile' in d:
+        d['makefile'] = False
+    elif 'makefile' not in d:
         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.''')
         do_prompt(d, 'makefile', 'Create Makefile? (y/n)', 'y', boolean)
-    if 'batchfile' not in d:
+    if 'no_batchfile' in d:
+        d['batchfile'] = False
+    elif 'batchfile' not in d:
         do_prompt(d, 'batchfile', 'Create Windows command file? (y/n)',
                   'y', boolean)
     print()
@@ -1257,8 +1278,7 @@ def generate(d, overwrite=True, silent=False):
     d['project_underline'] = column_width(d['project']) * '='
     extensions = (',\n' + indent).join(
         repr('sphinx.ext.' + name)
-        for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
-                     'pngmath', 'mathjax', 'ifconfig', 'viewcode')
+        for name in EXTENSIONS
         if d.get('ext_' + name))
     if extensions:
         d['extensions'] = '\n' + indent + extensions + ',\n'
@@ -1316,13 +1336,13 @@ def generate(d, overwrite=True, silent=False):
     masterfile = path.join(srcdir, d['master'] + d['suffix'])
     write_file(masterfile, MASTER_FILE % d)
 
-    if d['makefile']:
+    if d['makefile'] is True:
         d['rsrcdir'] = d['sep'] and 'source' or '.'
         d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
         # use binary mode, to avoid writing \r\n on Windows
         write_file(path.join(d['path'], 'Makefile'), MAKEFILE % d, u'\n')
 
-    if d['batchfile']:
+    if d['batchfile'] is True:
         d['rsrcdir'] = d['sep'] and 'source' or '.'
         d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
         write_file(path.join(d['path'], 'make.bat'), BATCHFILE % d, u'\r\n')
@@ -1344,24 +1364,141 @@ where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
 ''')
 
 
+def usage(argv, msg=None):
+    if msg:
+        print(msg, file=sys.stderr)
+        print(file=sys.stderr)
+
+USAGE = """\
+Sphinx v%s
+Usage: %%prog [options] [projectdir]
+""" % __version__
+
+EPILOG = """\
+For more information, visit <http://sphinx-doc.org/>.
+"""
+
+
+class MyFormatter(optparse.IndentedHelpFormatter):
+    def format_usage(self, usage):
+        return usage
+
+    def format_help(self, formatter):
+        result = []
+        if self.description:
+            result.append(self.format_description(formatter))
+        if self.option_list:
+            result.append(self.format_option_help(formatter))
+        return "\n".join(result)
+
+
 def main(argv=sys.argv):
     if not color_terminal():
         nocolor()
 
-    d = {}
-    if len(argv) > 3:
-        print('Usage: sphinx-quickstart [root]')
-        sys.exit(1)
-    elif len(argv) == 2:
-        d['path'] = argv[1]
+    parser = optparse.OptionParser(USAGE, epilog=EPILOG,
+                                   version='Sphinx v%s' % __version__,
+                                   formatter=MyFormatter())
+    parser.add_option('-q', '--quiet', action='store_true', dest='quiet',
+                      default=False,
+                      help='quiet mode')
+
+    group = parser.add_option_group('Structure options')
+    group.add_option('--sep', action='store_true', dest='sep',
+                     help='if specified, separate source and build dirs')
+    group.add_option('--dot', metavar='DOT', dest='dot',
+                     help='replacement for dot in _templates etc.')
+
+    group = parser.add_option_group('Project basic options')
+    group.add_option('-p', '--project', metavar='PROJECT', dest='project',
+                     help='project name')
+    group.add_option('-a', '--author', metavar='AUTHOR', dest='author',
+                     help='author names')
+    group.add_option('-v', metavar='VERSION', dest='version',
+                     help='version of project')
+    group.add_option('-r', '--release', metavar='RELEASE', dest='release',
+                     help='release of project')
+    group.add_option('-l', '--language', metavar='LANGUAGE', dest='language',
+                     help='document language')
+    group.add_option('--suffix', metavar='SUFFIX', dest='suffix',
+                     help='source file suffix')
+    group.add_option('--master', metavar='MASTER', dest='master',
+                     help='master document name')
+    group.add_option('--epub', action='store_true', dest='epub',
+                     default=False,
+                     help='use epub')
+
+    group = parser.add_option_group('Extension options')
+    for ext in EXTENSIONS:
+        group.add_option('--ext-' + ext, action='store_true',
+                         dest='ext_' + ext, default=False,
+                         help='enable %s extension' % ext)
+
+    group = parser.add_option_group('Makefile and Batchfile creation')
+    group.add_option('--makefile', action='store_true', dest='makefile',
+                     default=False,
+                     help='create makefile')
+    group.add_option('--no-makefile', action='store_true', dest='no_makefile',
+                     default=False,
+                     help='not create makefile')
+    group.add_option('--batchfile', action='store_true', dest='batchfile',
+                     default=False,
+                     help='create batchfile')
+    group.add_option('--no-batchfile', action='store_true', dest='no_batchfile',
+                     default=False,
+                     help='not create batchfile')
+
+    # parse options
     try:
-        ask_user(d)
+        opts, args = parser.parse_args()
+    except SystemExit as err:
+        return err.code
+
+    if len(args) > 0:
+        opts.ensure_value('path', args[0])
+
+    d = vars(opts)
+    for k, v in d.items():
+        # delete None or False value
+        if v is None or v is False:
+            del d[k]
+
+    try:
+        if 'quiet' in d:
+            if 'project' not in d or 'author' not in d or \
+               'version' not in d:
+                print('''"quiet" is specified, but any of "project", \
+"author" or "version" is not specified.''')
+                return
+
+        if all(['quiet' in d, 'project' in d, 'author' in d,
+                'version' in d]):
+            # quiet mode with all required params satisfied, use default
+            d.setdefault('release', d['version'])
+            d2 = DEFAULT_VALUE.copy()
+            d2.update(dict(("ext_"+ext, False) for ext in EXTENSIONS))
+            d2.update(d)
+            d = d2
+            if 'no_makefile' in d:
+                d['makefile'] = False
+            if 'no_batchfile' in d:
+                d['batchfile'] = False
+
+            if path.exists(d['path']) and (
+                    not path.isdir(d['path']) or os.listdir(d['path'])):
+                print()
+                print(bold('Error: specified path is not a directory, or not a'
+                           ' empty directory.'))
+                print('sphinx-quickstart only generate into a empty directory.'
+                      ' Please specify a new root path.')
+                return
+        else:
+            ask_user(d)
     except (KeyboardInterrupt, EOFError):
         print()
         print('[Interrupted.]')
         return
     generate(d)
 
-
 if __name__ == '__main__':
     sys.exit(main(sys.argv))

sphinx/themes/basic/layout.html

@@ -139,7 +139,7 @@
     {%- if hasdoc('copyright') %}
     <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
     {%- endif %}
-    <link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}" />
+    <link rel="top" title="{{ docstitle|e }}" href="{{ pathto(master_doc) }}" />
     {%- if parents %}
     <link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}" />
     {%- endif %}

sphinx/themes/bizstyle/static/bizstyle.css_t

@@ -244,13 +244,13 @@ cite, code, tt {
     letter-spacing: 0.01em;
 }
 
-tt {
+code {
     background-color: #F2F2F2;
     border-bottom: 1px solid #ddd;
     color: #333;
 }
 
-tt.descname, tt.descclassname, tt.xref {
+code.descname, code.descclassname, code.xref {
     border: 0;
 }
 
@@ -259,12 +259,12 @@ hr {
     margin: 2em;
 }
 
-a tt {
+a code {
     border: 0;
     color: #CA7900;
 }
 
-a tt:hover {
+a code:hover {
     color: #2491CF;
 }
 

tests/test_directive_code.py

@@ -61,7 +61,7 @@ def test_code_block_caption_html(app, status, warning):
 def test_code_block_caption_latex(app, status, warning):
     app.builder.build_all()
     latex = (app.outdir / 'Python.tex').text()
-    caption = '\\caption{\ncaption \\emph{test} rb\n}'
+    caption = '\\caption{caption \\emph{test} rb}'
     assert caption in latex
 
 
@@ -183,5 +183,5 @@ def test_literalinclude_caption_html(app, status, warning):
 def test_literalinclude_caption_latex(app, status, warning):
     app.builder.build('index')
     latex = (app.outdir / 'Python.tex').text()
-    caption = '\\caption{\ncaption \\textbf{test} py\n}'
+    caption = '\\caption{caption \\textbf{test} py}'
     assert caption in latex