diff options
Diffstat (limited to 'sphinx/cmdline.py')
| -rw-r--r-- | sphinx/cmdline.py | 137 |
1 files changed, 92 insertions, 45 deletions
diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 67d721f4..13bd2e9f 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -5,7 +5,7 @@ sphinx-build command-line handling. - :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ @@ -22,9 +22,17 @@ from sphinx.errors import SphinxError from sphinx.application import Sphinx from sphinx.util import Tee, format_exception_cut_frames, save_traceback from sphinx.util.console import red, nocolor, color_terminal +from sphinx.util.osutil import fs_encoding from sphinx.util.pycompat import terminal_safe, bytes +def abspath(pathdir): + pathdir = path.abspath(pathdir) + if isinstance(pathdir, bytes): + pathdir = pathdir.decode(fs_encoding) + return pathdir + + def usage(argv, msg=None): if msg: print >>sys.stderr, msg @@ -32,29 +40,47 @@ def usage(argv, msg=None): print >>sys.stderr, """\ Sphinx v%s Usage: %s [options] sourcedir outdir [filenames...] -Options: -b <builder> -- builder to use; default is html - -a -- write all files; default is to only write \ -new and changed files - -E -- don't use a saved environment, always read all files - -t <tag> -- include "only" blocks with <tag> - -d <path> -- path for the cached environment and doctree files - (default: outdir/.doctrees) - -c <path> -- path where configuration file (conf.py) is located + +General options +^^^^^^^^^^^^^^^ +-b <builder> builder to use; default is html +-a write all files; default is to only write new and changed files +-E don't use a saved environment, always read all files +-d <path> path for the cached environment and doctree files + (default: outdir/.doctrees) + +Build configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-c <path> path where configuration file (conf.py) is located (default: same as sourcedir) - -C -- use no config file at all, only -D options - -D <setting=value> -- override a setting in configuration - -A <name=value> -- pass a value into the templates, for HTML builder - -n -- nit-picky mode, warn about all missing references - -N -- do not do colored output - -q -- no output on stdout, just warnings on stderr - -Q -- no output at all, not even warnings - -w <file> -- write warnings (and errors) to given file - -W -- turn warnings into errors - -P -- run Pdb on exception -Modi: +-C use no config file at all, only -D options +-D <setting=value> override a setting in configuration file +-t <tag> define tag: include "only" blocks with <tag> +-A <name=value> pass a value into the templates, for HTML builder +-n nit-picky mode, warn about all missing references + +Console output options +^^^^^^^^^^^^^^^^^^^^^^ +-v increase verbosity (can be repeated) +-q no output on stdout, just warnings on stderr +-Q no output at all, not even warnings +-w <file> write warnings (and errors) to given file +-W turn warnings into errors +-T show full traceback on exception +-N do not emit colored output +-P run Pdb on exception + +Filename arguments +^^^^^^^^^^^^^^^^^^ * without -a and without filenames, write new and changed files. * with -a, write all files. -* with filenames, write these.""" % (__version__, argv[0]) +* with filenames, write these. + +Standard options +^^^^^^^^^^^^^^^^ +-h, --help show this help and exit +--version show version information and exit +""" % (__version__, argv[0]) def main(argv): @@ -63,30 +89,41 @@ def main(argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:P') + opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:nNEqQWw:PThv', + ['help', 'version']) allopts = set(opt[0] for opt in opts) - srcdir = confdir = path.abspath(args[0]) + if '-h' in allopts or '--help' in allopts: + usage(argv) + print >>sys.stderr + print >>sys.stderr, 'For more information, see '\ + '<http://sphinx-doc.org/>.' + return 0 + if '--version' in allopts: + print 'Sphinx (sphinx-build) %s' % __version__ + return 0 + srcdir = confdir = abspath(args[0]) if not path.isdir(srcdir): - print >>sys.stderr, 'Error: Cannot find source directory.' + print >>sys.stderr, 'Error: Cannot find source directory `%s\'.' % ( + srcdir,) return 1 if not path.isfile(path.join(srcdir, 'conf.py')) and \ '-c' not in allopts and '-C' not in allopts: print >>sys.stderr, ('Error: Source directory doesn\'t ' 'contain conf.py file.') return 1 - outdir = path.abspath(args[1]) - if not path.isdir(outdir): - print >>sys.stderr, 'Making output directory...' - os.makedirs(outdir) - except (IndexError, getopt.error): - usage(argv) + outdir = abspath(args[1]) + except getopt.error, err: + usage(argv, 'Error: %s' % err) + return 1 + except IndexError: + usage(argv, 'Error: Insufficient arguments.') return 1 filenames = args[2:] err = 0 for filename in filenames: if not path.isfile(filename): - print >>sys.stderr, 'Cannot find file %r.' % filename + print >>sys.stderr, 'Error: Cannot find file %r.' % filename err = 1 if err: return 1 @@ -100,6 +137,8 @@ def main(argv): buildername = None force_all = freshenv = warningiserror = use_pdb = False + show_traceback = False + verbosity = 0 status = sys.stdout warning = sys.stderr error = sys.stderr @@ -112,15 +151,15 @@ def main(argv): buildername = val elif opt == '-a': if filenames: - usage(argv, 'Cannot combine -a option and filenames.') + usage(argv, 'Error: Cannot combine -a option and filenames.') return 1 force_all = True elif opt == '-t': tags.append(val) elif opt == '-d': - doctreedir = path.abspath(val) + doctreedir = abspath(val) elif opt == '-c': - confdir = path.abspath(val) + confdir = abspath(val) if not path.isfile(path.join(confdir, 'conf.py')): print >>sys.stderr, ('Error: Configuration directory ' 'doesn\'t contain conf.py file.') @@ -176,26 +215,29 @@ def main(argv): warnfile = val elif opt == '-P': use_pdb = True + elif opt == '-T': + show_traceback = True + elif opt == '-v': + verbosity += 1 + show_traceback = True if warning and warnfile: warnfp = open(warnfile, 'w') warning = Tee(warning, warnfp) error = warning + if not path.isdir(outdir): + if status: + print >>status, 'Making output directory...' + os.makedirs(outdir) + try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning, freshenv, - warningiserror, tags) + warningiserror, tags, verbosity) app.build(force_all, filenames) return app.statuscode - except KeyboardInterrupt: - if use_pdb: - import pdb - print >>error, red('Interrupted while building, starting debugger:') - traceback.print_exc() - pdb.post_mortem(sys.exc_info()[2]) - return 1 - except Exception, err: + except (Exception, KeyboardInterrupt), err: if use_pdb: import pdb print >>error, red('Exception occurred while building, ' @@ -204,7 +246,12 @@ def main(argv): pdb.post_mortem(sys.exc_info()[2]) else: print >>error - if isinstance(err, SystemMessage): + if show_traceback: + traceback.print_exc(None, error) + print >>error + if isinstance(err, KeyboardInterrupt): + print >>error, 'interrupted!' + elif isinstance(err, SystemMessage): print >>error, red('reST markup error:') print >>error, terminal_safe(err.args[0]) elif isinstance(err, SphinxError): @@ -222,7 +269,7 @@ def main(argv): 'can be provided next time.') print >>error, ( 'Either send bugs to the mailing list at ' - '<http://groups.google.com/group/sphinx-dev/>,\n' + '<http://groups.google.com/group/sphinx-users/>,\n' 'or report them in the tracker at ' '<http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!') return 1 |