def main(argv):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], "ab:t:d:c:CD:A:nNEqQWw:PThvj:", ["help", "version"])
allopts = set(opt[0] for opt in opts)
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 `%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 = abspath(args[1])
except getopt.error, err:
usage(argv, "Error: %s" % err)
return 1
def main(argv):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:PThv',
['help', 'version'])
allopts = set(opt[0] for opt in opts)
if '-h' in allopts or '--help' in allopts:
usage(argv)
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 `%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 = abspath(args[1])
if not path.isdir(outdir):
print >>sys.stderr, 'Making output directory...'
os.makedirs(outdir)
except getopt.error, err:
usage(argv, 'Error: %s' % err)
return 1
def run(self):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
if not self.verbose:
status_stream = StringIO()
else:
status_stream = sys.stdout
confoverrides = {}
if self.project:
confoverrides['project'] = self.project
if self.version:
confoverrides['version'] = self.version
if self.release:
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
app = Sphinx(self.source_dir, self.config_dir,
self.builder_target_dir, self.doctree_dir,
self.builder, confoverrides, status_stream,
freshenv=self.fresh_env)
try:
app.build(force_all=self.all_files)
except Exception, err:
from docutils.utils import SystemMessage
if isinstance(err, SystemMessage):
print >>sys.stderr, darkred('reST markup error:')
print >>sys.stderr, err.args[0].encode('ascii',
'backslashreplace')
else:
raise
def run(self):
if not sys.stdout.isatty() or sys.platform == 'win32':
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
if not self.verbose:
status_stream = StringIO()
else:
status_stream = sys.stdout
app = Sphinx(self.source_dir, self.source_dir,
self.builder_target_dir, self.doctree_dir,
self.builder, {}, status_stream,
freshenv=self.fresh_env)
try:
if self.all_files:
app.builder.build_all()
else:
app.builder.build_update()
except Exception, err:
from docutils.utils import SystemMessage
if isinstance(err, SystemMessage):
sys.stderr, darkred('reST markup error:')
print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace')
else:
raise
def build_help(self):
# type: () -> None
if not color_terminal():
nocolor()
print(bold("Sphinx v%s" % sphinx.__display_version__))
print("Please use `make %s' where %s is one of" % ((blue('target'),) * 2)) # type: ignore # NOQA
for osname, bname, description in BUILDERS:
if not osname or os.name == osname:
print(' %s %s' % (blue(bname.ljust(10)), description))
def setup_logger(verbose=1, color=True):
"""
Sets up and returns a Python Logger instance for the Sage
documentation builder. The optional argument sets logger's level
and message format.
"""
# Set up colors. Adapted from sphinx.cmdline.
import sphinx.util.console as c
if not color or not sys.stdout.isatty() or not c.color_terminal():
c.nocolor()
# Available colors: black, darkgray, (dark)red, dark(green),
# brown, yellow, (dark)blue, purple, fuchsia, turquoise, teal,
# lightgray, white. Available styles: reset, bold, faint,
# standout, underline, blink.
# Set up log record formats.
format_std = "%(message)s"
formatter = logging.Formatter(format_std)
# format_debug = "%(module)s #%(lineno)s %(funcName)s() %(message)s"
fields = ["%(module)s", "#%(lineno)s", "%(funcName)s()", "%(message)s"]
colors = ["darkblue", "darkred", "brown", "reset"]
styles = ["reset", "reset", "reset", "reset"]
format_debug = ""
for i in xrange(len(fields)):
format_debug += c.colorize(styles[i], c.colorize(colors[i], fields[i]))
if i != len(fields):
format_debug += " "
# Documentation: http://docs.python.org/library/logging.html
logger = logging.getLogger("doc.common.builder")
# Note: There's also Handler.setLevel(). The argument is the
# lowest severity message that the respective logger or handler
# will pass on. The default levels are DEBUG, INFO, WARNING,
# ERROR, and CRITICAL. We use "WARNING" for normal verbosity and
# "ERROR" for quiet operation. It's possible to define custom
# levels. See the documentation for details.
if verbose == 0:
logger.setLevel(logging.ERROR)
if verbose == 1:
logger.setLevel(logging.WARNING)
if verbose == 2:
logger.setLevel(logging.INFO)
if verbose == 3:
logger.setLevel(logging.DEBUG)
formatter = logging.Formatter(format_debug)
handler = logging.StreamHandler()
handler.setFormatter(formatter)
logger.addHandler(handler)
return logger
def main(argv):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
# parse options
try:
opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:nNEqQWw:PThvj:',
['help', 'version'])
except getopt.error, err:
usage(argv, 'Error: %s' % err)
return 1
def run(self):
if is_sphinx_installed():
from sphinx.application import Sphinx
from sphinx.util.console import nocolor
# Windows' poor cmd box doesn't understand ANSI sequences
if not sys.stdout.isatty() or sys.platform == 'win32':
nocolor()
# Check to see if version information is provided in setup.py
# If it is, it will override version information in conf.py.
conf_overrides = {}
version = self.distribution.get_version()
if version != "0.0.0":
conf_overrides['version'] = version
conf_overrides['release'] = version
for i in range(len(self.source_dirs)):
for format in self.formats:
try:
builder_target = os.path.join(self.target_dir, format,
self.projects[i])
doctree_dir = os.path.join(builder_target, '.doctrees')
self.mkpath(doctree_dir)
# The sphinx interface requires 7 arguments: sourcedir,
# confdir, outdir, doctreedir, buildername,
# confoverrides, and status
app = Sphinx(self.source_dirs[i], self.source_dirs[i],
builder_target, doctree_dir, format, conf_overrides,
self.status_stream
)
app.builder.build_update()
if self.pdf_build and format == 'latex':
try:
os.chdir(builder_target)
subprocess.call(["make", "all-pdf"])
log.info("PDF doc created in %s."
% builder_target)
except Exception, e:
log.error(e)
except IOError, e:
log.warn(e)
except Exception, e:
log.error('Unable to generate %s docs.' % format)
if format == 'html' and len(self.formats) == 1:
log.info("Installing %s html documentation from zip"
" file.\n" % self.distribution.get_name())
unzip_html_docs(HTML_ZIP, TARGET_DIR)
def ablog_start(**kwargs):
if not color_terminal():
nocolor()
d = CONF_DEFAULTS
try:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print('')
print('[Interrupted.]')
return
generate(d)
def run(self):
if not color_terminal():
nocolor()
if not self.verbose:
status_stream = StringIO()
else:
status_stream = sys.stdout
confoverrides = {}
if self.project:
confoverrides['project'] = self.project
if self.version:
confoverrides['version'] = self.version
if self.release:
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
if self.copyright:
confoverrides['copyright'] = self.copyright
app = Sphinx(self.source_dir, self.config_dir,
self.builder_target_dir, self.doctree_dir,
self.builder, confoverrides, status_stream,
freshenv=self.fresh_env,
warningiserror=self.warning_is_error)
try:
app.build(force_all=self.all_files)
if app.statuscode:
raise DistutilsExecError(
'caused by %s builder.' % app.builder.name)
except Exception as err:
if self.pdb:
import pdb
print(darkred('Exception occurred while building, starting debugger:'),
file=sys.stderr)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
from docutils.utils import SystemMessage
if isinstance(err, SystemMessage):
print(darkred('reST markup error:'), file=sys.stderr)
print(err.args[0].encode('ascii', 'backslashreplace'),
file=sys.stderr)
else:
raise
if self.link_index:
src = app.config.master_doc + app.builder.out_suffix
dst = app.builder.get_outfilename('index')
os.symlink(src, dst)
def run(self):
# type: () -> None
if not color_terminal():
nocolor()
if not self.verbose: # type: ignore
status_stream = StringIO()
else:
status_stream = sys.stdout # type: ignore
confoverrides = {} # type: Dict[str, Any]
if self.project:
confoverrides['project'] = self.project
if self.version:
confoverrides['version'] = self.version
if self.release:
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
if self.copyright:
confoverrides['copyright'] = self.copyright
if self.nitpicky:
confoverrides['nitpicky'] = self.nitpicky
for builder, builder_target_dir in self.builder_target_dirs:
app = None
try:
confdir = self.config_dir or self.source_dir
with patch_docutils(confdir), docutils_namespace():
app = Sphinx(self.source_dir, self.config_dir,
builder_target_dir, self.doctree_dir,
builder, confoverrides, status_stream,
freshenv=self.fresh_env,
warningiserror=self.warning_is_error)
app.build(force_all=self.all_files)
if app.statuscode:
raise DistutilsExecError(
'caused by %s builder.' % app.builder.name)
except Exception as exc:
handle_exception(app, self, exc, sys.stderr)
if not self.pdb:
raise SystemExit(1)
if not self.link_index:
continue
src = app.config.master_doc + app.builder.out_suffix # type: ignore
dst = app.builder.get_outfilename('index') # type: ignore
os.symlink(src, dst)
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]
try:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print
print '[Interrupted.]'
return
generate(d)
def run(self):
if not color_terminal():
nocolor()
if not self.verbose:
status_stream = StringIO()
else:
status_stream = sys.stdout
confoverrides = {}
if self.project:
confoverrides["project"] = self.project
if self.version:
confoverrides["version"] = self.version
if self.release:
confoverrides["release"] = self.release
if self.today:
confoverrides["today"] = self.today
if self.copyright:
confoverrides["copyright"] = self.copyright
try:
with docutils_namespace():
app = Sphinx(
self.source_dir,
self.config_dir,
self.builder_target_dir,
self.doctree_dir,
self.builder,
confoverrides,
status_stream,
freshenv=self.fresh_env,
warningiserror=self.warning_is_error,
)
app.build(force_all=self.all_files)
if app.statuscode:
raise DistutilsExecError("caused by %s builder." % app.builder.name)
except Exception as exc:
handle_exception(app, self, exc, sys.stderr)
if not self.pdb:
raise SystemExit(1)
if self.link_index:
src = app.config.master_doc + app.builder.out_suffix
dst = app.builder.get_outfilename("index")
os.symlink(src, dst)
def main(argv=sys.argv):
# delay-import these to be able to get sphinx.__version__ from setup.py
# even without docutils installed
from sphinx.application import Sphinx, SphinxError
from docutils.utils import SystemMessage
if not sys.stdout.isatty() or sys.platform == 'win32':
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:NEqP')
srcdir = confdir = path.abspath(args[0])
if not path.isdir(srcdir):
print >>sys.stderr, 'Error: Cannot find source directory.'
return 1
if not path.isfile(path.join(srcdir, 'conf.py')) and \
'-c' not in (opt[0] for opt in opts):
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, 'Error: Cannot find output directory.'
return 1
except (IndexError, getopt.error):
usage(argv)
return 1
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print >>sys.stderr, 'Cannot find file %r.' % filename
err = 1
if err:
return 1
buildername = all_files = None
freshenv = use_pdb = False
status = sys.stdout
confoverrides = {}
doctreedir = path.join(outdir, '.doctrees')
for opt, val in opts:
if opt == '-b':
buildername = val
elif opt == '-a':
if filenames:
usage(argv, 'Cannot combine -a option and filenames.')
return 1
all_files = True
elif opt == '-d':
doctreedir = path.abspath(val)
elif opt == '-c':
confdir = path.abspath(val)
if not path.isfile(path.join(confdir, 'conf.py')):
print >>sys.stderr, \
'Error: Configuration directory doesn\'t contain conf.py file.'
return 1
elif opt == '-D':
key, val = val.split('=')
try:
val = int(val)
except ValueError:
pass
confoverrides[key] = val
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = StringIO()
elif opt == '-P':
use_pdb = True
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,
confoverrides, status, sys.stderr, freshenv)
app.build(all_files, filenames)
except KeyboardInterrupt:
if use_pdb:
import pdb
print >>sys.stderr, darkred('Interrupted while building, starting debugger:')
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
return 1
except Exception, err:
if use_pdb:
import pdb
print >>sys.stderr, darkred('Exception occurred while building, '
'starting debugger:')
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
if isinstance(err, SystemMessage):
print >>sys.stderr, darkred('reST markup error:')
print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace')
elif isinstance(err, SphinxError):
print >>sys.stderr, darkred('%s:' % err.category)
print >>sys.stderr, err
else:
print >>sys.stderr, darkred('Exception occurred:')
print >>sys.stderr, format_exception_cut_frames().rstrip()
tbpath = save_traceback()
print >>sys.stderr, darkred('The full traceback has been saved '
'in %s, if you want to report the '
'issue to the author.' % tbpath)
print >>sys.stderr, ('Please also report this if it was a user '
'error, so that a better error message '
'can be provided next time.')
print >>sys.stderr, ('Send reports to [email protected]. '
'Thanks!')
return 1
def build_main(argv: List[str] = sys.argv[1:]) -> int:
"""Sphinx build "main" command-line entry."""
parser = get_parser()
args = parser.parse_args(argv)
if args.noconfig:
args.confdir = None
elif not args.confdir:
args.confdir = args.sourcedir
if not args.doctreedir:
args.doctreedir = os.path.join(args.outputdir, '.doctrees')
# handle remaining filename arguments
filenames = args.filenames
missing_files = []
for filename in filenames:
if not os.path.isfile(filename):
missing_files.append(filename)
if missing_files:
parser.error(__('cannot find files %r') % missing_files)
if args.force_all and filenames:
parser.error(__('cannot combine -a option and filenames'))
if args.color == 'no' or (args.color == 'auto' and not color_terminal()):
nocolor()
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if args.quiet:
status = None
if args.really_quiet:
status = warning = None
if warning and args.warnfile:
try:
warnfp = open(args.warnfile, 'w')
except Exception as exc:
parser.error(
__('cannot open warning file %r: %s') % (args.warnfile, exc))
warning = Tee(warning, warnfp) # type: ignore
error = warning
confoverrides = {}
for val in args.define:
try:
key, val = val.split('=', 1)
except ValueError:
parser.error(
__('-D option argument must be in the form name=value'))
confoverrides[key] = val
for val in args.htmldefine:
try:
key, val = val.split('=')
except ValueError:
parser.error(
__('-A option argument must be in the form name=value'))
try:
val = int(val)
except ValueError:
pass
confoverrides['html_context.%s' % key] = val
if args.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
confdir = args.confdir or args.sourcedir
with patch_docutils(confdir), docutils_namespace():
app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
args.doctreedir, args.builder, confoverrides, status,
warning, args.freshenv, args.warningiserror,
args.tags, args.verbosity, args.jobs, args.keep_going)
app.build(args.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
handle_exception(app, args, exc, error)
return 2
def main(argv=sys.argv[1:]):
# type: (List[str]) -> int
locale.setlocale(locale.LC_ALL, '')
sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
if not color_terminal():
nocolor()
# parse options
parser = get_parser()
try:
args = parser.parse_args(argv)
except SystemExit as err:
return err.code
d = vars(args)
# delete None or False value
d = dict((k, v) for k, v in d.items() if not (v is None or v is False))
try:
if 'quiet' in d:
if not set(['project', 'author']).issubset(d):
print(__('''"quiet" is specified, but any of "project" or \
"author" is not specified.'''))
return 1
if set(['quiet', 'project', 'author']).issubset(d):
# quiet mode with all required params satisfied, use default
d.setdefault('version', '')
d.setdefault('release', d['version'])
d2 = DEFAULTS.copy()
d2.update(d)
d = d2
if not valid_dir(d):
print()
print(bold(__('Error: specified path is not a directory, or sphinx'
' files already exist.')))
print(__('sphinx-quickstart only generate into a empty directory.'
' Please specify a new root path.'))
return 1
else:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print()
print('[Interrupted.]')
return 130 # 128 + SIGINT
# decode values in d if value is a Python string literal
for key, value in d.items():
if isinstance(value, binary_type):
d[key] = term_decode(value)
# handle use of CSV-style extension values
d.setdefault('extensions', [])
for ext in d['extensions'][:]:
if ',' in ext:
d['extensions'].remove(ext)
d['extensions'].extend(ext.split(','))
for variable in d.get('variables', []):
try:
name, value = variable.split('=')
d[name] = value
except ValueError:
print(__('Invalid template variable: %s') % variable)
generate(d, templatedir=args.templatedir)
return 0
def main(argv):
if not color_terminal():
nocolor()
parser = optparse.OptionParser(USAGE, epilog=EPILOG, formatter=MyFormatter())
parser.add_option('--version', action='store_true', dest='version',
help='show version information and exit')
group = parser.add_option_group('General options')
group.add_option('-b', metavar='BUILDER', dest='builder', default='html',
help='builder to use; default is html')
group.add_option('-a', action='store_true', dest='force_all',
help='write all files; default is to only write new and '
'changed files')
group.add_option('-E', action='store_true', dest='freshenv',
help='don\'t use a saved environment, always read '
'all files')
group.add_option('-d', metavar='PATH', default=None, dest='doctreedir',
help='path for the cached environment and doctree files '
'(default: outdir/.doctrees)')
group.add_option('-j', metavar='N', default=1, type='int', dest='jobs',
help='build in parallel with N processes where possible')
# this option never gets through to this point (it is intercepted earlier)
# group.add_option('-M', metavar='BUILDER', dest='make_mode',
# help='"make" mode -- as used by Makefile, like '
# '"sphinx-build -M html"')
group = parser.add_option_group('Build configuration options')
group.add_option('-c', metavar='PATH', dest='confdir',
help='path where configuration file (conf.py) is located '
'(default: same as sourcedir)')
group.add_option('-C', action='store_true', dest='noconfig',
help='use no config file at all, only -D options')
group.add_option('-D', metavar='setting=value', action='append',
dest='define', default=[],
help='override a setting in configuration file')
group.add_option('-A', metavar='name=value', action='append',
dest='htmldefine', default=[],
help='pass a value into HTML templates')
group.add_option('-t', metavar='TAG', action='append',
dest='tags', default=[],
help='define tag: include "only" blocks with TAG')
group.add_option('-n', action='store_true', dest='nitpicky',
help='nit-picky mode, warn about all missing references')
group = parser.add_option_group('Console output options')
group.add_option('-v', action='count', dest='verbosity', default=0,
help='increase verbosity (can be repeated)')
group.add_option('-q', action='store_true', dest='quiet',
help='no output on stdout, just warnings on stderr')
group.add_option('-Q', action='store_true', dest='really_quiet',
help='no output at all, not even warnings')
group.add_option('-N', action='store_true', dest='nocolor',
help='do not emit colored output')
group.add_option('-w', metavar='FILE', dest='warnfile',
help='write warnings (and errors) to given file')
group.add_option('-W', action='store_true', dest='warningiserror',
help='turn warnings into errors')
group.add_option('-T', action='store_true', dest='traceback',
help='show full traceback on exception')
group.add_option('-P', action='store_true', dest='pdb',
help='run Pdb on exception')
# parse options
try:
opts, args = parser.parse_args(argv[1:])
except SystemExit as err:
return err.code
# handle basic options
if opts.version:
print('Sphinx (sphinx-build) %s' % __version__)
return 0
# get paths (first and second positional argument)
try:
srcdir = abspath(args[0])
confdir = abspath(opts.confdir or srcdir)
if opts.noconfig:
confdir = None
if not path.isdir(srcdir):
print('Error: Cannot find source directory `%s\'.' % srcdir,
file=sys.stderr)
return 1
if not opts.noconfig and not path.isfile(path.join(confdir, 'conf.py')):
print('Error: Config directory doesn\'t contain a conf.py file.',
file=sys.stderr)
return 1
outdir = abspath(args[1])
except IndexError:
usage(argv, 'Error: Insufficient arguments.')
return 1
except UnicodeError:
print(
'Error: Multibyte filename not supported on this filesystem '
'encoding (%r).' % fs_encoding, file=sys.stderr)
return 1
# handle remaining filename arguments
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print('Error: Cannot find file %r.' % filename, file=sys.stderr)
err = 1
if err:
return 1
# likely encoding used for command-line arguments
try:
locale = __import__('locale') # due to submodule of the same name
likely_encoding = locale.getpreferredencoding()
except Exception:
likely_encoding = None
if opts.force_all and filenames:
print('Error: Cannot combine -a option and filenames.', file=sys.stderr)
return 1
if opts.nocolor:
nocolor()
doctreedir = abspath(opts.doctreedir or path.join(outdir, '.doctrees'))
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if opts.quiet:
status = None
if opts.really_quiet:
status = warning = None
if warning and opts.warnfile:
try:
warnfp = open(opts.warnfile, 'w')
except Exception as exc:
print('Error: Cannot open warning file %r: %s' %
(opts.warnfile, exc), file=sys.stderr)
sys.exit(1)
warning = Tee(warning, warnfp)
error = warning
confoverrides = {}
for val in opts.define:
try:
key, val = val.split('=')
except ValueError:
print('Error: -D option argument must be in the form name=value.',
file=sys.stderr)
return 1
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides[key] = val
for val in opts.htmldefine:
try:
key, val = val.split('=')
except ValueError:
print('Error: -A option argument must be in the form name=value.',
file=sys.stderr)
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
if opts.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, opts.builder,
confoverrides, status, warning, opts.freshenv,
opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
app.build(opts.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as err:
if opts.pdb:
import pdb
print(red('Exception occurred while building, starting debugger:'),
file=error)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
print(file=error)
if opts.verbosity or opts.traceback:
traceback.print_exc(None, error)
print(file=error)
if isinstance(err, KeyboardInterrupt):
print('interrupted!', file=error)
elif isinstance(err, SystemMessage):
print(red('reST markup error:'), file=error)
print(terminal_safe(err.args[0]), file=error)
elif isinstance(err, SphinxError):
print(red('%s:' % err.category), file=error)
print(terminal_safe(text_type(err)), file=error)
elif isinstance(err, UnicodeError):
print(red('Encoding error:'), file=error)
print(terminal_safe(text_type(err)), file=error)
tbpath = save_traceback(app)
print(red('The full traceback has been saved in %s, if you want '
'to report the issue to the developers.' % tbpath),
file=error)
else:
print(red('Exception occurred:'), file=error)
print(format_exception_cut_frames().rstrip(), file=error)
tbpath = save_traceback(app)
print(red('The full traceback has been saved in %s, if you '
'want to report the issue to the developers.' % tbpath),
file=error)
print('Please also report this if it was a user error, so '
'that a better error message can be provided next time.',
file=error)
print('A bug report can be filed in the tracker at '
'<https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!',
file=error)
return 1
def main(argv):
if not color_terminal():
nocolor()
parser = optparse.OptionParser(USAGE,
epilog=EPILOG,
formatter=MyFormatter())
parser.add_option('--version',
action='store_true',
dest='version',
help='show version information and exit')
group = parser.add_option_group('General options')
group.add_option('-b',
metavar='BUILDER',
dest='builder',
default='html',
help='builder to use; default is html')
group.add_option('-a',
action='store_true',
dest='force_all',
help='write all files; default is to only write new and '
'changed files')
group.add_option('-E',
action='store_true',
dest='freshenv',
help='don\'t use a saved environment, always read '
'all files')
group.add_option('-d',
metavar='PATH',
default=None,
dest='doctreedir',
help='path for the cached environment and doctree files '
'(default: outdir/.doctrees)')
group.add_option('-j',
metavar='N',
default=1,
type='int',
dest='jobs',
help='build in parallel with N processes where possible')
# this option never gets through to this point (it is intercepted earlier)
# group.add_option('-M', metavar='BUILDER', dest='make_mode',
# help='"make" mode -- as used by Makefile, like '
# '"sphinx-build -M html"')
group = parser.add_option_group('Build configuration options')
group.add_option('-c',
metavar='PATH',
dest='confdir',
help='path where configuration file (conf.py) is located '
'(default: same as sourcedir)')
group.add_option('-C',
action='store_true',
dest='noconfig',
help='use no config file at all, only -D options')
group.add_option('-D',
metavar='setting=value',
action='append',
dest='define',
default=[],
help='override a setting in configuration file')
group.add_option('-A',
metavar='name=value',
action='append',
dest='htmldefine',
default=[],
help='pass a value into HTML templates')
group.add_option('-t',
metavar='TAG',
action='append',
dest='tags',
default=[],
help='define tag: include "only" blocks with TAG')
group.add_option('-n',
action='store_true',
dest='nitpicky',
help='nit-picky mode, warn about all missing references')
group = parser.add_option_group('Console output options')
group.add_option('-v',
action='count',
dest='verbosity',
default=0,
help='increase verbosity (can be repeated)')
group.add_option('-q',
action='store_true',
dest='quiet',
help='no output on stdout, just warnings on stderr')
group.add_option('-Q',
action='store_true',
dest='really_quiet',
help='no output at all, not even warnings')
group.add_option('-N',
action='store_true',
dest='nocolor',
help='do not emit colored output')
group.add_option('-w',
metavar='FILE',
dest='warnfile',
help='write warnings (and errors) to given file')
group.add_option('-W',
action='store_true',
dest='warningiserror',
help='turn warnings into errors')
group.add_option('-T',
action='store_true',
dest='traceback',
help='show full traceback on exception')
group.add_option('-P',
action='store_true',
dest='pdb',
help='run Pdb on exception')
# parse options
try:
opts, args = parser.parse_args(list(argv[1:]))
except SystemExit as err:
return err.code
# handle basic options
if opts.version:
print('Sphinx (sphinx-build) %s' % __display_version__)
return 0
# get paths (first and second positional argument)
try:
srcdir = abspath(args[0])
confdir = abspath(opts.confdir or srcdir)
if opts.noconfig:
confdir = None
if not path.isdir(srcdir):
print('Error: Cannot find source directory `%s\'.' % srcdir,
file=sys.stderr)
return 1
if not opts.noconfig and not path.isfile(path.join(confdir,
'conf.py')):
print('Error: Config directory doesn\'t contain a conf.py file.',
file=sys.stderr)
return 1
outdir = abspath(args[1])
except IndexError:
parser.print_help()
return 1
except UnicodeError:
print('Error: Multibyte filename not supported on this filesystem '
'encoding (%r).' % fs_encoding,
file=sys.stderr)
return 1
# handle remaining filename arguments
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print('Error: Cannot find file %r.' % filename, file=sys.stderr)
err = 1
if err:
return 1
# likely encoding used for command-line arguments
try:
locale = __import__('locale') # due to submodule of the same name
likely_encoding = locale.getpreferredencoding()
except Exception:
likely_encoding = None
if opts.force_all and filenames:
print('Error: Cannot combine -a option and filenames.',
file=sys.stderr)
return 1
if opts.nocolor:
nocolor()
doctreedir = abspath(opts.doctreedir or path.join(outdir, '.doctrees'))
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if opts.quiet:
status = None
if opts.really_quiet:
status = warning = None
if warning and opts.warnfile:
try:
warnfp = open(opts.warnfile, 'w')
except Exception as exc:
print('Error: Cannot open warning file %r: %s' %
(opts.warnfile, exc),
file=sys.stderr)
sys.exit(1)
warning = Tee(warning, warnfp)
error = warning
confoverrides = {}
for val in opts.define:
try:
key, val = val.split('=')
except ValueError:
print('Error: -D option argument must be in the form name=value.',
file=sys.stderr)
return 1
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides[key] = val
for val in opts.htmldefine:
try:
key, val = val.split('=')
except ValueError:
print('Error: -A option argument must be in the form name=value.',
file=sys.stderr)
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
if opts.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, opts.builder,
confoverrides, status, warning, opts.freshenv,
opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
app.build(opts.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as err:
if opts.pdb:
import pdb
print(red('Exception occurred while building, starting debugger:'),
file=error)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
print(file=error)
if opts.verbosity or opts.traceback:
traceback.print_exc(None, error)
print(file=error)
if isinstance(err, KeyboardInterrupt):
print('interrupted!', file=error)
elif isinstance(err, SystemMessage):
print(red('reST markup error:'), file=error)
print(terminal_safe(err.args[0]), file=error)
elif isinstance(err, SphinxError):
print(red('%s:' % err.category), file=error)
print(terminal_safe(text_type(err)), file=error)
elif isinstance(err, UnicodeError):
print(red('Encoding error:'), file=error)
print(terminal_safe(text_type(err)), file=error)
tbpath = save_traceback(app)
print(red(
'The full traceback has been saved in %s, if you want '
'to report the issue to the developers.' % tbpath),
file=error)
else:
print(red('Exception occurred:'), file=error)
print(format_exception_cut_frames().rstrip(), file=error)
tbpath = save_traceback(app)
print(red('The full traceback has been saved in %s, if you '
'want to report the issue to the developers.' %
tbpath),
file=error)
print(
'Please also report this if it was a user error, so '
'that a better error message can be provided next time.',
file=error)
print(
'A bug report can be filed in the tracker at '
'<https://github.com/sphinx-doc/sphinx/issues>. Thanks!',
file=error)
return 1
def setup_module():
nocolor()
def main(argv):
"""
Based mostly on sphinx.cmdline.main
"""
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:P')
allopts = set(opt[0] for opt in opts)
srcdir = confdir = os.path.abspath(args[0])
if not os.path.isdir(srcdir):
print >>sys.stderr, 'Error: Cannot find source directory.'
return 1
if not os.path.isfile(os.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 = os.path.abspath(args[1])
if not os.path.isdir(outdir):
print >>sys.stderr, 'Making output directory...'
os.makedirs(outdir)
except (IndexError, getopt.error):
usage(argv)
return 1
filenames = args[2:]
err = 0
for filename in filenames:
if not os.path.isfile(filename):
print >> sys.stderr, 'Cannot find file %r.' % filename
err = 1
if err:
return 1
buildername = None
force_all = freshenv = warningiserror = False
status = sys.stdout
warning = sys.stderr
confoverrides = {}
tags = []
doctreedir = os.path.join(outdir, '.doctrees')
for opt, val in opts:
if opt == '-b':
buildername = val
elif opt == '-a':
if filenames:
usage(argv, 'Cannot combine -a option and filenames.')
return 1
force_all = True
elif opt == '-t':
tags.append(val)
elif opt == '-d':
doctreedir = os.path.abspath(val)
elif opt == '-c':
confdir = os.path.abspath(val)
if not os.path.isfile(os.path.join(confdir, 'conf.py')):
print >> sys.stderr, \
'Error: Configuration directory doesn\'t contain conf.py file.'
return 1
elif opt == '-C':
confdir = None
elif opt == '-D':
try:
key, val = val.split('=')
except ValueError:
print >> sys.stderr, \
'Error: -D option argument must be in the form name=value.'
return 1
try:
val = int(val)
except ValueError:
pass
confoverrides[key] = val
elif opt == '-A':
try:
key, val = val.split('=')
except ValueError:
print >> sys.stderr, \
'Error: -A option argument must be in the form name=value.'
return 1
try:
val = int(val)
except ValueError:
pass
confoverrides['html_context.%s' % key] = val
elif opt == '-n':
confoverrides['nitpicky'] = True
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = None
elif opt == '-Q':
status = None
warning = None
elif opt == '-W':
warningiserror = True
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,
confoverrides, status, warning, freshenv,
warningiserror, tags)
app.build(force_all, filenames)
return app.statuscode
except KeyboardInterrupt:
return 1
except Exception as err:
print >> sys.stderr
if isinstance(err, SystemMessage):
print >> sys.stderr, red('reST markup error:')
print >> sys.stderr, err.args[0].encode('ascii', 'backslashreplace')
elif isinstance(err, SphinxError):
print >> sys.stderr, red('%s:' % err.category)
print >> sys.stderr, err
else:
raise
return 1
def main(argv=sys.argv[1:]):
# type: (List[str]) -> int
if not color_terminal():
nocolor()
# parse options
parser = get_parser()
try:
args = parser.parse_args(argv)
except SystemExit as err:
return err.code
d = vars(args)
# delete None or False value
d = dict((k, v) for k, v in d.items() if not (v is None or v is False))
try:
if 'quiet' in d:
if not set(['project', 'author']).issubset(d):
print('''"quiet" is specified, but any of "project" or \
"author" is not specified.''')
return 1
if set(['quiet', 'project', 'author']).issubset(d):
# quiet mode with all required params satisfied, use default
d.setdefault('version', '')
d.setdefault('release', d['version'])
d2 = DEFAULTS.copy()
d2.update(d)
d = d2
if not valid_dir(d):
print()
print(
bold('Error: specified path is not a directory, or sphinx'
' files already exist.'))
print('sphinx-quickstart only generate into a empty directory.'
' Please specify a new root path.')
return 1
else:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print()
print('[Interrupted.]')
return 130 # 128 + SIGINT
# decode values in d if value is a Python string literal
for key, value in d.items():
if isinstance(value, binary_type):
d[key] = term_decode(value)
# handle use of CSV-style extension values
d.setdefault('extensions', [])
for ext in d['extensions'][:]:
if ',' in ext:
d['extensions'].remove(ext)
d['extensions'].extend(ext.split(','))
for variable in d.get('variables', []):
try:
name, value = variable.split('=')
d[name] = value
except ValueError:
print('Invalid template variable: %s' % variable)
generate(d, templatedir=args.templatedir)
return 0
def run(self):
if not self.distribution.doc_modules:
return
## Make sure that sources are complete in build_lib.
self.run_command('build_src')
## Ditto extensions
self.run_command('build_ext')
build = self.get_finalized_command('build')
buildpy = self.get_finalized_command('build_py')
target = os.path.abspath(os.path.join(build.build_base, 'http'))
mkdir(target)
build_verbose = self.distribution.verbose
environ = self.distribution.environment
for dext in self.distribution.doc_modules:
if self.distribution.verbose:
print('building documentation "' + dext.name + '" sources')
doc_dir = os.path.abspath(dext.source_directory)
extra_dirs = dext.extra_directories
working_dir = os.path.abspath(os.path.join(self.build_temp,
dext.source_directory))
here = os.getcwd()
reprocess = True
ref = os.path.join(target, dext.name + '.html')
root_dir = dext.name
if os.path.exists(ref) and not self.force:
reprocess = False
docbase = os.path.join(doc_dir, 'modules')
for root, dirnames, filenames in os.walk(docbase):
for fn in fnmatch.filter(filenames, '*.rst'):
doc = os.path.join(root, fn)
if os.path.getmtime(ref) < os.path.getmtime(doc):
reprocess = True
break
src = os.path.join(root_dir, root[len(docbase)+1:],
fn[:-3] + 'py')
if os.path.exists(src):
if os.path.getmtime(ref) < os.path.getmtime(src):
reprocess = True
break
if reprocess:
src_dirs = []
for package in buildpy.packages:
# Locate package source directory
src_dirs.append(os.path.abspath(buildpy.get_package_dir(package)))
#FIXME rst files in package sources (mutiple packages)
#src_dir = src_dirs[0]
src_dir = os.path.abspath('.')
bld_dir = os.path.abspath(self.build_lib)
doc_bld_dir = os.path.join(bld_dir,
os.path.relpath(doc_dir, src_dir))
environ['BUILD_DIR'] = bld_dir
environ['SOURCE_DIR'] = src_dir
environ['RELATIVE_SOURCE_DIR'] = os.path.relpath(src_dir,
doc_bld_dir)
copy_tree(doc_dir, working_dir, True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
for d in extra_dirs:
subdir = os.path.basename(os.path.normpath(d))
copy_tree(d, os.path.join(target, subdir), True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
## Configure rst files
configure_files(environ, src_dir, '*.rst', working_dir)
if os.path.exists(os.path.join(doc_dir, dext.doxygen_cfg)):
## Doxygen + breathe
'Config ' + os.path.join(doc_dir, dext.doxygen_cfg)
configure_file(environ,
os.path.join(doc_dir, dext.doxygen_cfg),
os.path.join(working_dir, dext.doxygen_cfg),
style=dext.style)
for s in dext.doxygen_srcs:
configure_file(environ,
os.path.join(doc_dir, s),
os.path.join(working_dir, s),
style=dext.style)
try:
doxygen_exe = find_program('doxygen')
except:
sys.stderr.write('ERROR: Doxygen not installed ' +
'(required for documentation).\n')
return
reprocess = True
ref = os.path.join(working_dir, 'html', 'index.html')
if os.path.exists(ref) and not self.force:
reprocess = False
for d in environ['C_SOURCE_DIRS'].split(' '):
for orig in glob.glob(os.path.join(d, '*.h*')):
if os.path.getmtime(ref) < \
os.path.getmtime(orig):
reprocess = True
break
if reprocess:
if self.distribution.verbose:
out = sys.stdout
err = sys.stderr
else:
out = err = open('doxygen.log', 'w')
os.chdir(working_dir)
cmd_line = [doxygen_exe, dext.doxygen_cfg]
status = subprocess.call(cmd_line,
stdout=out, stderr=err)
if status != 0:
raise Exception("Command '" + str(cmd_line) +
"' returned non-zero exit status "
+ str(status))
if not self.distribution.verbose:
out.close()
copy_tree('html', os.path.join(target, 'html'), True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
os.chdir(here)
create_breathe_stylesheet(target)
for f in dext.extra_docs:
shutil.copy(os.path.join(doc_dir, f), target)
## Sphinx
if dext.without_sphinx:
return
if dext.sphinx_config is None:
dext.sphinx_config = os.path.join(os.path.dirname(__file__),
'sphinx_conf.py.in')
elif os.path.dirname(dext.sphinx_config) == '':
dext.sphinx_config = os.path.join(doc_dir,
dext.sphinx_config)
configure_file(environ, dext.sphinx_config,
os.path.join(working_dir, 'conf.py'))
import warnings
try:
import sphinx
from sphinx.application import Sphinx
if 'windows' in platform.system().lower() or \
not build_verbose:
from sphinx.util.console import nocolor
except:
sys.stderr.write('ERROR: Sphinx not installed ' +
'(required for documentation).\n')
return
warnings.filterwarnings("ignore",
category=PendingDeprecationWarning)
warnings.filterwarnings("ignore", category=UserWarning)
status = sys.stdout
if not build_verbose:
status = open('sphinx.log', 'w')
if 'windows' in platform.system().lower() or not build_verbose:
nocolor()
try:
sphinx_app = Sphinx(working_dir, working_dir, target,
os.path.join(target, '.doctrees'),
'html', None, status)
sphinx_app.build(True)
except Exception:
if build_verbose:
e = sys.exc_info()[1]
print('ERROR: ' + str(e))
else:
pass
if not build_verbose:
status.close()
warnings.resetwarnings()
def setup_module():
nocolor()
def run(self):
if not self.distribution.doc_modules:
return
## Make sure that sources are complete in build_lib.
self.run_command('build_src')
## Ditto extensions
self.run_command('build_ext')
build = self.get_finalized_command('build')
buildpy = self.get_finalized_command('build_py')
## packages and files are in build.build_lib (see build_py.py)
target = os.path.join(os.path.abspath(build.build_base), 'http')
mkdir(target)
build_verbose = self.distribution.verbose
environ = self.distribution.environment
for dext in self.distribution.doc_modules:
if self.distribution.verbose:
print('building documentation "' + dext.name + '" sources')
doc_dir = os.path.abspath(dext.source_directory)
extra_dirs = dext.extra_directories
src_dir = os.path.abspath(dext.name)
here = os.getcwd()
reprocess = True
ref = os.path.join(target, dext.name + '.html')
root_dir = dext.name
if os.path.exists(ref) and not self.force:
reprocess = False
for root, _, filenames in os.walk(src_dir):
for fn in fnmatch.filter(filenames, '*.rst'):
doc = os.path.join(root, fn)
if os.path.getmtime(ref) < os.path.getmtime(doc):
reprocess = True
break
src = os.path.join(root_dir, root[len(doc_dir)+1:],
fn[:-3] + 'py')
if os.path.exists(src):
if os.path.getmtime(ref) < os.path.getmtime(src):
reprocess = True
break
if reprocess:
working_dir = os.path.abspath(build.build_lib)
for package in buildpy.packages:
pkgdir = buildpy.get_package_dir(package)
pkgsrcdir = os.path.join(os.path.dirname(src_dir), pkgdir)
configure_files(environ, pkgsrcdir,
'*.rst', os.path.join(working_dir, pkgdir))
cfg_dir = os.path.join(working_dir, dext.source_directory)
environ['BUILD_DIR'] = working_dir
copy_tree(doc_dir, working_dir, True,
excludes=[dext.name, '.svn', 'CVS', '.git', '.hg*'])
copy_tree(os.path.join(doc_dir, dext.name),
os.path.join(cfg_dir, dext.name), True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
for d in extra_dirs:
subdir = os.path.basename(os.path.normpath(d))
copy_tree(d, os.path.join(target, subdir), True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
if os.path.exists(os.path.join(doc_dir, dext.doxygen_cfg)):
## Doxygen + breathe
print('Config ' + os.path.join(doc_dir, dext.doxygen_cfg))
configure_file(environ,
os.path.join(doc_dir, dext.doxygen_cfg),
os.path.join(working_dir, dext.doxygen_cfg),
style=dext.style)
for s in dext.doxygen_srcs:
configure_file(environ,
os.path.join(doc_dir, s),
os.path.join(working_dir, s),
style=dext.style)
try:
doxygen_exe = find_program('doxygen')
except Exception: # pylint: disable=W0703
sys.stderr.write('ERROR: Doxygen not installed ' +
'(required for documentation).\n')
return
reprocess = True
ref = os.path.join(working_dir, 'html', 'index.html')
if os.path.exists(ref) and not self.force:
reprocess = False
for d in environ['C_SOURCE_DIRS'].split(' '):
for orig in glob.glob(os.path.join(d, '*.h*')):
if os.path.getmtime(ref) < \
os.path.getmtime(orig):
reprocess = True
break
if reprocess:
if self.distribution.verbose:
out = sys.stdout
err = sys.stderr
else:
out = err = open('doxygen.log', 'w')
os.chdir(working_dir)
cmd_line = [doxygen_exe, dext.doxygen_cfg]
status = subprocess.call(cmd_line,
stdout=out, stderr=err)
if status != 0:
raise Exception("Command '" + str(cmd_line) +
"' returned non-zero exit status "
+ str(status))
if not self.distribution.verbose:
out.close()
copy_tree('html', os.path.join(target, 'html'), True,
excludes=['.svn', 'CVS', '.git', '.hg*'])
copy_tree('xml', os.path.join(cfg_dir, 'xml'), True)
os.chdir(here)
create_breathe_stylesheet(target)
for f in dext.extra_docs:
shutil.copy(os.path.join(doc_dir, f), target)
## Sphinx
if dext.without_sphinx:
return
if dext.sphinx_config is None:
level_up = os.path.dirname(os.path.dirname(__file__))
dext.sphinx_config = os.path.join(level_up,
'sphinx_conf.py.in')
elif os.path.dirname(dext.sphinx_config) == '':
dext.sphinx_config = os.path.join(doc_dir,
dext.sphinx_config)
configure_file(environ, dext.sphinx_config,
os.path.join(cfg_dir, 'conf.py'))
import warnings
try:
import sphinx # pylint: disable=W0612
except ImportError:
configure_package('breathe') ## requires sphinx
sys.path.insert(0, os.path.join(options.target_build_dir,
options.local_lib_dir))
from sphinx.application import Sphinx
if 'windows' in platform.system().lower() or \
not build_verbose:
from sphinx.util.console import nocolor
warnings.filterwarnings("ignore",
category=PendingDeprecationWarning)
warnings.filterwarnings("ignore", category=UserWarning)
status = sys.stdout
if not build_verbose:
status = open('sphinx.log', 'w')
if 'windows' in platform.system().lower() or not build_verbose:
nocolor()
try:
## args: srcdir, confdir, outdir, doctreedir, buildername
sphinx_app = Sphinx(os.path.join(working_dir, dext.name),
cfg_dir, target,
os.path.join(target, '.doctrees'),
'html', status=status)
sphinx_app.build(force_all=True, filenames=None)
except Exception: # pylint: disable=W0703
if build_verbose:
print('ERROR: ' + str(sys.exc_info()[1]))
else:
pass
if not build_verbose:
status.close()
warnings.resetwarnings()
def prepare_sphinx(src_dir, config=None, out_dir=None, extra_config=None,
builder=None, relax=False):
"""
prepare a sphinx application instance
Return a prepared Sphinx application instance [1] ready for execution.
[1]: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/application.py
Args:
src_dir: document sources
config (optional): configuration to use
out_dir (optional): output for generated documents
extra_config (optional): additional configuration data to apply
builder (optional): the builder to use
relax (optional): do not generate warnings as errors
"""
# Enable coloring of warning and other messages. Note that this can
# cause sys.stderr to be mocked which is why we pass the new value
# explicitly on the call to Sphinx() below.
if 'MSYSTEM' not in os.environ and not color_terminal():
nocolor()
conf = dict(config) if config else {}
if extra_config:
conf.update(extra_config)
conf_dir = src_dir if config is None else None
warnerr = not relax
sts = None
if 'SPHINX_STATUS' in os.environ:
sts = sys.stdout
verbosity = 0
if 'SPHINX_VERBOSITY' in os.environ:
try:
verbosity = int(os.environ['SPHINX_VERBOSITY'])
except ValueError:
pass
# default to using this extension's builder
if not builder:
builder = 'confluence'
if not out_dir:
# 3 = prepare_dirs, this, contextmanager
out_dir = prepare_dirs(f_back_count=3)
doctrees_dir = os.path.join(out_dir, '.doctrees')
# support pre-Sphinx v4.0 installations which do not have `root_doc` by
# swapping to the obsolete configuration name
if parse_version(sphinx_version) < parse_version('4.0'):
if 'root_doc' in conf:
conf['master_doc'] = conf['root_doc']
del conf['root_doc']
with docutils_namespace():
app = Sphinx(
src_dir, # output for document sources
conf_dir, # configuration directory
out_dir, # output for generated documents
doctrees_dir, # output for doctree files
builder, # builder to execute
confoverrides=conf, # load provided configuration (volatile)
status=sts, # status output
warning=sys.stderr, # warnings output
warningiserror=warnerr, # treat warnings as errors
verbosity=verbosity) # verbosity
yield app
def setUp(self):
nocolor()
def main(argv):
# type: (List[unicode]) -> int
parser = optparse.OptionParser(USAGE,
epilog=EPILOG,
formatter=MyFormatter())
parser.add_option('--version',
action='store_true',
dest='version',
help='show version information and exit')
group = parser.add_option_group('General options')
group.add_option('-b',
metavar='BUILDER',
dest='builder',
default='html',
help='builder to use; default is html')
group.add_option('-a',
action='store_true',
dest='force_all',
help='write all files; default is to only write new and '
'changed files')
group.add_option('-E',
action='store_true',
dest='freshenv',
help='don\'t use a saved environment, always read '
'all files')
group.add_option('-d',
metavar='PATH',
default=None,
dest='doctreedir',
help='path for the cached environment and doctree files '
'(default: outdir/.doctrees)')
group.add_option('-j',
metavar='N',
default=1,
type='int',
dest='jobs',
help='build in parallel with N processes where possible')
# this option never gets through to this point (it is intercepted earlier)
# group.add_option('-M', metavar='BUILDER', dest='make_mode',
# help='"make" mode -- as used by Makefile, like '
# '"sphinx-build -M html"')
group = parser.add_option_group('Build configuration options')
group.add_option('-c',
metavar='PATH',
dest='confdir',
help='path where configuration file (conf.py) is located '
'(default: same as sourcedir)')
group.add_option('-C',
action='store_true',
dest='noconfig',
help='use no config file at all, only -D options')
group.add_option('-D',
metavar='setting=value',
action='append',
dest='define',
default=[],
help='override a setting in configuration file')
group.add_option('-A',
metavar='name=value',
action='append',
dest='htmldefine',
default=[],
help='pass a value into HTML templates')
group.add_option('-t',
metavar='TAG',
action='append',
dest='tags',
default=[],
help='define tag: include "only" blocks with TAG')
group.add_option('-n',
action='store_true',
dest='nitpicky',
help='nit-picky mode, warn about all missing references')
group = parser.add_option_group('Console output options')
group.add_option('-v',
action='count',
dest='verbosity',
default=0,
help='increase verbosity (can be repeated)')
group.add_option('-q',
action='store_true',
dest='quiet',
help='no output on stdout, just warnings on stderr')
group.add_option('-Q',
action='store_true',
dest='really_quiet',
help='no output at all, not even warnings')
group.add_option('--color',
dest='color',
action='store_const',
const='yes',
default='auto',
help='Do emit colored output (default: auto-detect)')
group.add_option('-N',
'--no-color',
dest='color',
action='store_const',
const='no',
help='Do not emit colored output (default: auot-detect)')
group.add_option('-w',
metavar='FILE',
dest='warnfile',
help='write warnings (and errors) to given file')
group.add_option('-W',
action='store_true',
dest='warningiserror',
help='turn warnings into errors')
group.add_option('-T',
action='store_true',
dest='traceback',
help='show full traceback on exception')
group.add_option('-P',
action='store_true',
dest='pdb',
help='run Pdb on exception')
# parse options
try:
opts, args = parser.parse_args(list(argv[1:]))
except SystemExit as err:
return err.code
# handle basic options
if opts.version:
print('Sphinx (sphinx-build) %s' % __display_version__)
return 0
# get paths (first and second positional argument)
try:
srcdir = abspath(args[0])
confdir = abspath(opts.confdir or srcdir)
if opts.noconfig:
confdir = None
if not path.isdir(srcdir):
print('Error: Cannot find source directory `%s\'.' % srcdir,
file=sys.stderr)
return 1
if not opts.noconfig and not path.isfile(path.join(confdir,
'conf.py')):
print('Error: Config directory doesn\'t contain a conf.py file.',
file=sys.stderr)
return 1
outdir = abspath(args[1])
if srcdir == outdir:
print(
'Error: source directory and destination directory are same.',
file=sys.stderr)
return 1
except IndexError:
parser.print_help()
return 1
except UnicodeError:
print('Error: Multibyte filename not supported on this filesystem '
'encoding (%r).' % fs_encoding,
file=sys.stderr)
return 1
# handle remaining filename arguments
filenames = args[2:]
errored = False
for filename in filenames:
if not path.isfile(filename):
print('Error: Cannot find file %r.' % filename, file=sys.stderr)
errored = True
if errored:
return 1
# likely encoding used for command-line arguments
try:
locale = __import__('locale') # due to submodule of the same name
likely_encoding = locale.getpreferredencoding()
except Exception:
likely_encoding = None
if opts.force_all and filenames:
print('Error: Cannot combine -a option and filenames.',
file=sys.stderr)
return 1
if opts.color == 'no' or (opts.color == 'auto' and not color_terminal()):
nocolor()
doctreedir = abspath(opts.doctreedir or path.join(outdir, '.doctrees'))
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if opts.quiet:
status = None
if opts.really_quiet:
status = warning = None
if warning and opts.warnfile:
try:
warnfp = open(opts.warnfile, 'w')
except Exception as exc:
print('Error: Cannot open warning file %r: %s' %
(opts.warnfile, exc),
file=sys.stderr)
sys.exit(1)
warning = Tee(warning, warnfp) # type: ignore
error = warning
confoverrides = {}
for val in opts.define:
try:
key, val = val.split('=', 1)
except ValueError:
print('Error: -D option argument must be in the form name=value.',
file=sys.stderr)
return 1
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides[key] = val
for val in opts.htmldefine:
try:
key, val = val.split('=')
except ValueError:
print('Error: -A option argument must be in the form name=value.',
file=sys.stderr)
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
if opts.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
with docutils_namespace():
app = Sphinx(srcdir, confdir, outdir, doctreedir, opts.builder,
confoverrides, status, warning, opts.freshenv,
opts.warningiserror, opts.tags, opts.verbosity,
opts.jobs)
app.build(opts.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
handle_exception(app, opts, exc, error)
return 1
def main(argv):
# type: (List[unicode]) -> int
parser = optparse.OptionParser(USAGE, epilog=EPILOG, formatter=MyFormatter())
parser.add_option('--version', action='store_true', dest='version',
help='show version information and exit')
group = parser.add_option_group('General options')
group.add_option('-b', metavar='BUILDER', dest='builder', default='html',
help='builder to use; default is html')
group.add_option('-a', action='store_true', dest='force_all',
help='write all files; default is to only write new and '
'changed files')
group.add_option('-E', action='store_true', dest='freshenv',
help='don\'t use a saved environment, always read '
'all files')
group.add_option('-d', metavar='PATH', default=None, dest='doctreedir',
help='path for the cached environment and doctree files '
'(default: outdir/.doctrees)')
group.add_option('-j', metavar='N', default=1, type='int', dest='jobs',
help='build in parallel with N processes where possible')
# this option never gets through to this point (it is intercepted earlier)
# group.add_option('-M', metavar='BUILDER', dest='make_mode',
# help='"make" mode -- as used by Makefile, like '
# '"sphinx-build -M html"')
group = parser.add_option_group('Build configuration options')
group.add_option('-c', metavar='PATH', dest='confdir',
help='path where configuration file (conf.py) is located '
'(default: same as sourcedir)')
group.add_option('-C', action='store_true', dest='noconfig',
help='use no config file at all, only -D options')
group.add_option('-D', metavar='setting=value', action='append',
dest='define', default=[],
help='override a setting in configuration file')
group.add_option('-A', metavar='name=value', action='append',
dest='htmldefine', default=[],
help='pass a value into HTML templates')
group.add_option('-t', metavar='TAG', action='append',
dest='tags', default=[],
help='define tag: include "only" blocks with TAG')
group.add_option('-n', action='store_true', dest='nitpicky',
help='nit-picky mode, warn about all missing references')
group = parser.add_option_group('Console output options')
group.add_option('-v', action='count', dest='verbosity', default=0,
help='increase verbosity (can be repeated)')
group.add_option('-q', action='store_true', dest='quiet',
help='no output on stdout, just warnings on stderr')
group.add_option('-Q', action='store_true', dest='really_quiet',
help='no output at all, not even warnings')
group.add_option('--color', dest='color',
action='store_const', const='yes', default='auto',
help='Do emit colored output (default: auto-detect)')
group.add_option('-N', '--no-color', dest='color',
action='store_const', const='no',
help='Do not emit colored output (default: auot-detect)')
group.add_option('-w', metavar='FILE', dest='warnfile',
help='write warnings (and errors) to given file')
group.add_option('-W', action='store_true', dest='warningiserror',
help='turn warnings into errors')
group.add_option('-T', action='store_true', dest='traceback',
help='show full traceback on exception')
group.add_option('-P', action='store_true', dest='pdb',
help='run Pdb on exception')
# parse options
try:
opts, args = parser.parse_args(list(argv[1:]))
except SystemExit as err:
return err.code
# handle basic options
if opts.version:
print('Sphinx (sphinx-build) %s' % __display_version__)
return 0
# get paths (first and second positional argument)
try:
srcdir = abspath(args[0])
confdir = abspath(opts.confdir or srcdir)
if opts.noconfig:
confdir = None
if not path.isdir(srcdir):
print('Error: Cannot find source directory `%s\'.' % srcdir,
file=sys.stderr)
return 1
if not opts.noconfig and not path.isfile(path.join(confdir, 'conf.py')):
print('Error: Config directory doesn\'t contain a conf.py file.',
file=sys.stderr)
return 1
outdir = abspath(args[1])
if srcdir == outdir:
print('Error: source directory and destination directory are same.',
file=sys.stderr)
return 1
except IndexError:
parser.print_help()
return 1
except UnicodeError:
print(
'Error: Multibyte filename not supported on this filesystem '
'encoding (%r).' % fs_encoding, file=sys.stderr)
return 1
# handle remaining filename arguments
filenames = args[2:]
errored = False
for filename in filenames:
if not path.isfile(filename):
print('Error: Cannot find file %r.' % filename, file=sys.stderr)
errored = True
if errored:
return 1
# likely encoding used for command-line arguments
try:
locale = __import__('locale') # due to submodule of the same name
likely_encoding = locale.getpreferredencoding()
except Exception:
likely_encoding = None
if opts.force_all and filenames:
print('Error: Cannot combine -a option and filenames.', file=sys.stderr)
return 1
if opts.color == 'no' or (opts.color == 'auto' and not color_terminal()):
nocolor()
doctreedir = abspath(opts.doctreedir or path.join(outdir, '.doctrees'))
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if opts.quiet:
status = None
if opts.really_quiet:
status = warning = None
if warning and opts.warnfile:
try:
warnfp = open(opts.warnfile, 'w')
except Exception as exc:
print('Error: Cannot open warning file %r: %s' %
(opts.warnfile, exc), file=sys.stderr)
sys.exit(1)
warning = Tee(warning, warnfp) # type: ignore
error = warning
confoverrides = {}
for val in opts.define:
try:
key, val = val.split('=', 1)
except ValueError:
print('Error: -D option argument must be in the form name=value.',
file=sys.stderr)
return 1
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides[key] = val
for val in opts.htmldefine:
try:
key, val = val.split('=')
except ValueError:
print('Error: -A option argument must be in the form name=value.',
file=sys.stderr)
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
if opts.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
with docutils_namespace():
app = Sphinx(srcdir, confdir, outdir, doctreedir, opts.builder,
confoverrides, status, warning, opts.freshenv,
opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
app.build(opts.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
handle_exception(app, opts, exc, error)
return 1
def main(argv=sys.argv):
if not sys.stdout.isatty() or sys.platform == 'win32':
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], 'ab:d:D:NEqP')
srcdir = path.abspath(args[0])
if not path.isdir(srcdir):
print >>sys.stderr, 'Error: Cannot find source directory.'
return 1
if not path.isfile(path.join(srcdir, 'conf.py')):
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, 'Error: Cannot find output directory.'
return 1
except (IndexError, getopt.error):
usage(argv)
return 1
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print >>sys.stderr, 'Cannot find file %r.' % filename
err = 1
if err:
return 1
buildername = all_files = None
freshenv = use_pdb = False
status = sys.stdout
confoverrides = {}
doctreedir = path.join(outdir, '.doctrees')
for opt, val in opts:
if opt == '-b':
buildername = val
elif opt == '-a':
if filenames:
usage(argv, 'Cannot combine -a option and filenames.')
return 1
all_files = True
elif opt == '-d':
doctreedir = val
elif opt == '-D':
key, val = val.split('=')
try:
val = int(val)
except: pass
confoverrides[key] = val
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = StringIO()
elif opt == '-P':
use_pdb = True
try:
app = Sphinx(srcdir, outdir, doctreedir, buildername,
confoverrides, status, sys.stderr, freshenv)
if not app.builder:
return 1
if all_files:
app.builder.build_all()
elif filenames:
app.builder.build_specific(filenames)
else:
app.builder.build_update()
except KeyboardInterrupt:
# catches BaseExceptions in 2.5 -- SystemExit, KeyboardInterrupt
return 1
except SystemExit:
return 0
except Exception, err:
if use_pdb:
import pdb
print >>sys.stderr, darkred('Exception occurred while building, '
'starting debugger:')
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
if isinstance(err, SystemMessage):
print >>sys.stderr, darkred('reST markup error:')
print >>sys.stderr, str(err)
else:
print >>sys.stderr, darkred('Exception occurred:')
print >>sys.stderr, format_exception_cut_frames().rstrip()
tbpath = save_traceback()
print >>sys.stderr, darkred('The full traceback has been saved '
'in %s, if you want to report the '
'issue to the author.' % tbpath)
print >>sys.stderr, ('Please also report this if it was a user '
'error, so that a better error message '
'can be provided next time.')
print >>sys.stderr, 'Send reports to [email protected]. Thanks!'
return 1
def build_main(argv=sys.argv[1:]):
# type: (List[str]) -> int
"""Sphinx build "main" command-line entry."""
parser = get_parser()
args = parser.parse_args(argv)
if args.noconfig:
args.confdir = None
elif not args.confdir:
args.confdir = args.sourcedir
if not args.doctreedir:
args.doctreedir = os.path.join(args.outputdir, '.doctrees')
# handle remaining filename arguments
filenames = args.filenames
missing_files = []
for filename in filenames:
if not os.path.isfile(filename):
missing_files.append(filename)
if missing_files:
parser.error(__('cannot find files %r') % missing_files)
if args.force_all and filenames:
parser.error(__('cannot combine -a option and filenames'))
if args.color == 'no' or (args.color == 'auto' and not color_terminal()):
nocolor()
status = sys.stdout
warning = sys.stderr
error = sys.stderr
if args.quiet:
status = None
if args.really_quiet:
status = warning = None
if warning and args.warnfile:
try:
warnfp = open(args.warnfile, 'w')
except Exception as exc:
parser.error(__('cannot open warning file %r: %s') % (
args.warnfile, exc))
warning = Tee(warning, warnfp) # type: ignore
error = warning
confoverrides = {}
for val in args.define:
try:
key, val = val.split('=', 1)
except ValueError:
parser.error(__('-D option argument must be in the form name=value'))
confoverrides[key] = val
for val in args.htmldefine:
try:
key, val = val.split('=')
except ValueError:
parser.error(__('-A option argument must be in the form name=value'))
try:
val = int(val)
except ValueError:
pass
confoverrides['html_context.%s' % key] = val
if args.nitpicky:
confoverrides['nitpicky'] = True
app = None
try:
confdir = args.confdir or args.sourcedir
with patch_docutils(confdir), docutils_namespace():
app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
args.doctreedir, args.builder, confoverrides, status,
warning, args.freshenv, args.warningiserror,
args.tags, args.verbosity, args.jobs, args.keep_going)
app.build(args.force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
handle_exception(app, args, exc, error)
return 2
print >> sys.stderr, ('Error: -A option argument must be '
'in the form name=value.')
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, bytes):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
elif opt == '-n':
confoverrides['nitpicky'] = True
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = None
elif opt == '-Q':
status = None
warning = None
elif opt == '-W':
warningiserror = True
elif opt == '-w':
warnfile = val
elif opt == '-P':
use_pdb = True
elif opt == '-T':
show_traceback = True
def inner_main(args):
d = {}
if os.name == 'nt' or not sys.stdout.isatty():
nocolor()
print bold('Welcome to the Sphinx quickstart utility.')
print '''
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).'''
print '''
Enter the root path for documentation.'''
do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
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.'''
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)
print '''
The project name will occur in several places in the built documentation.'''
do_prompt(d, 'project', 'Project name')
do_prompt(d, 'author', 'Author name(s)')
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.'''
do_prompt(d, 'version', 'Project version')
do_prompt(d, 'release', 'Project release', d['version'])
print '''
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.'''
do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix)
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.'''
do_prompt(d, 'master', 'Name of your master document (without suffix)',
'index')
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)
do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets '
'in doctest blocks (y/n)', 'n', boolean)
print '''
If you are under Unix, a Makefile 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)
d['project_fn'] = make_filename(d['project'])
d['year'] = time.strftime('%Y')
d['now'] = time.asctime()
d['underline'] = len(d['project']) * '='
d['extensions'] = ', '.join(
repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest')
if d['ext_' + name].upper() in ('Y', 'YES'))
if not path.isdir(d['path']):
mkdir_p(d['path'])
separate = d['sep'].upper() in ('Y', 'YES')
srcdir = separate and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if separate:
builddir = path.join(d['path'], 'build')
else:
builddir = path.join(srcdir, d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
f = open(path.join(srcdir, 'conf.py'), 'w')
f.write(QUICKSTART_CONF % d)
f.close()
masterfile = path.join(srcdir, d['master'] + d['suffix'])
f = open(masterfile, 'w')
f.write(MASTER_FILE % d)
f.close()
create_makefile = d['makefile'].upper() in ('Y', 'YES')
if create_makefile:
d['rsrcdir'] = separate and 'source' or '.'
d['rbuilddir'] = separate and 'build' or d['dot'] + 'build'
f = open(path.join(d['path'], 'Makefile'), 'w')
f.write(MAKEFILE % d)
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. Use the sphinx-build script to build the docs, like so:
''' % masterfile + (create_makefile and '''
make <builder>
''' or '''
sphinx-build -b <builder> %s %s
''' % (srcdir, builddir))
import re
import os
import sys
import time
import codecs
from django.conf import settings
from django.contrib import messages
from sphinx import builders
from sphinx.application import Sphinx
from sphinx.util.console import nocolor
from sphinx.builders.html import SerializingHTMLBuilder
from sphinx.util.osutil import ensuredir, os_path
nocolor()
try:
SETTINGS = settings.MEZE_SETTINGS
except AttributeError:
SETTINGS = {}
WORKDIR = SETTINGS.get('workdir', settings.PROJECT_ROOT)
IMGEXTS = set(['.gif', '.png', '.jpg'])
try:
SPHINX_CONF = settings.SPHINX_CONF
except AttributeError:
SPHINX_CONF = """project = copyright = u''
version = release = '0'
master_doc = 'index'
def main(argv):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
try:
opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:P')
allopts = set(opt[0] for opt in opts)
srcdir = confdir = path.abspath(args[0])
if not path.isdir(srcdir):
print >>sys.stderr, 'Error: Cannot find source directory.'
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)
return 1
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print >>sys.stderr, 'Cannot find file %r.' % filename
err = 1
if err:
return 1
buildername = None
force_all = freshenv = warningiserror = use_pdb = False
status = sys.stdout
warning = sys.stderr
error = sys.stderr
warnfile = None
confoverrides = {}
tags = []
doctreedir = path.join(outdir, '.doctrees')
for opt, val in opts:
if opt == '-b':
buildername = val
elif opt == '-a':
if filenames:
usage(argv, 'Cannot combine -a option and filenames.')
return 1
force_all = True
elif opt == '-t':
tags.append(val)
elif opt == '-d':
doctreedir = path.abspath(val)
elif opt == '-c':
confdir = path.abspath(val)
if not path.isfile(path.join(confdir, 'conf.py')):
print >>sys.stderr, ('Error: Configuration directory '
'doesn\'t contain conf.py file.')
return 1
elif opt == '-C':
confdir = None
elif opt == '-D':
try:
key, val = val.split('=')
except ValueError:
print >>sys.stderr, ('Error: -D option argument must be '
'in the form name=value.')
return 1
try:
val = int(val)
except ValueError:
pass
confoverrides[key] = val
elif opt == '-A':
try:
key, val = val.split('=')
except ValueError:
print >>sys.stderr, ('Error: -A option argument must be '
'in the form name=value.')
return 1
try:
val = int(val)
except ValueError:
pass
confoverrides['html_context.%s' % key] = val
elif opt == '-n':
confoverrides['nitpicky'] = True
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = None
elif opt == '-Q':
status = None
warning = None
elif opt == '-W':
warningiserror = True
elif opt == '-w':
warnfile = val
elif opt == '-P':
use_pdb = True
if warning and warnfile:
warnfp = open(warnfile, 'w')
warning = Tee(warning, warnfp)
error = warning
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,
confoverrides, status, warning, freshenv,
warningiserror, tags)
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:
if use_pdb:
import pdb
print >>error, red('Exception occurred while building, '
'starting debugger:')
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
print >>error
if isinstance(err, SystemMessage):
print >>error, red('reST markup error:')
print >>error, err.args[0].encode('ascii', 'backslashreplace')
elif isinstance(err, SphinxError):
print >>error, red('%s:' % err.category)
print >>error, err
else:
print >>error, red('Exception occurred:')
print >>error, format_exception_cut_frames().rstrip()
tbpath = save_traceback()
print >>error, red('The full traceback has been saved '
'in %s, if you want to report the '
'issue to the developers.' % tbpath)
print >>error, ('Please also report this if it was a user '
'error, so that a better error message '
'can be provided next time.')
print >>error, (
'Either send bugs to the mailing list at '
'<http://groups.google.com/group/sphinx-dev/>,\n'
'or report them in the tracker at '
'<http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!')
return 1
def inner_main(args):
d = {}
texescape.init()
if not color_terminal():
nocolor()
print bold('Welcome to the Sphinx quickstart utility.')
print '''
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).'''
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
do_prompt(d, 'path', 'Please enter a new root path (or just Enter '
'to exit)', '', is_path)
if not d['path']:
sys.exit(1)
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.'''
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. 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.'''
do_prompt(d, 'project', 'Project name')
do_prompt(d, 'author', 'Author name(s)')
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.'''
do_prompt(d, 'version', 'Project version')
do_prompt(d, 'release', 'Project release', d['version'])
print '''
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.'''
do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix)
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.'''
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
do_prompt(d, 'master', 'Please enter a new file name, or rename the '
'existing file and press Enter', d['master'])
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)
do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets '
'in doctest blocks (y/N)', 'n', boolean)
do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx '
'documentation of different projects (y/N)', 'n', boolean)
do_prompt(d, 'ext_todo', 'todo: write "todo" entries '
'that can be shown or hidden on build (y/N)', 'n', boolean)
do_prompt(d, 'ext_coverage', 'coverage: checks for documentation '
'coverage (y/N)', 'n', boolean)
do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered '
'as PNG images (y/N)', 'n', boolean)
do_prompt(d, 'ext_jsmath', 'jsmath: include math, rendered in the '
'browser by JSMath (y/N)', 'n', boolean)
if d['ext_pngmath'] and d['ext_jsmath']:
print '''Note: pngmath and jsmath cannot be enabled at the same time.
pngmath has been deselected.'''
do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of '
'content based on config values (y/N)', 'n', boolean)
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)
do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)',
'y', boolean)
d['project_fn'] = make_filename(d['project'])
d['now'] = time.asctime()
d['underline'] = len(d['project']) * '='
d['extensions'] = ', '.join(
repr('sphinx.ext.' + name)
for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
'pngmath', 'jsmath', 'ifconfig')
if d['ext_' + name])
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
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(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'copyright', 'author_texescaped',
'project_doc_texescaped', 'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_trees'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_trees'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
conf_text = QUICKSTART_CONF % d
if d['ext_intersphinx']:
conf_text += INTERSPHINX_CONFIG
f = open(path.join(srcdir, 'conf.py'), 'w')
f.write(conf_text.encode('utf-8'))
f.close()
masterfile = path.join(srcdir, d['master'] + d['suffix'])
f = open(masterfile, 'w')
f.write((MASTER_FILE % d).encode('utf-8'))
f.close()
if d['makefile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
f = open(path.join(d['path'], 'Makefile'), 'w')
f.write((MAKEFILE % d).encode('utf-8'))
f.close()
if d['batchfile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] 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 + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
def main(argv):
if not color_terminal():
# Windows' poor cmd box doesn't understand ANSI sequences
nocolor()
# parse options
try:
opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:nNEqQWw:PThvj:',
['help', 'version'])
except getopt.error as err:
usage(argv, 'Error: %s' % err)
return 1
# handle basic options
allopts = set(opt[0] for opt in opts)
# help and version options
if '-h' in allopts or '--help' in allopts:
usage(argv)
print(file=sys.stderr)
print('For more information, see <http://sphinx-doc.org/>.',
file=sys.stderr)
return 0
if '--version' in allopts:
print('Sphinx (sphinx-build) %s' % __version__)
return 0
# get paths (first and second positional argument)
try:
srcdir = confdir = abspath(args[0])
if not path.isdir(srcdir):
print('Error: Cannot find source directory `%s\'.' % srcdir,
file=sys.stderr)
return 1
if not path.isfile(path.join(srcdir, 'conf.py')) and \
'-c' not in allopts and '-C' not in allopts:
print('Error: Source directory doesn\'t contain a conf.py file.',
file=sys.stderr)
return 1
outdir = abspath(args[1])
except IndexError:
usage(argv, 'Error: Insufficient arguments.')
return 1
except UnicodeError:
print(
'Error: Multibyte filename not supported on this filesystem '
'encoding (%r).' % fs_encoding, file=sys.stderr)
return 1
# handle remaining filename arguments
filenames = args[2:]
err = 0
for filename in filenames:
if not path.isfile(filename):
print('Error: Cannot find file %r.' % filename, file=sys.stderr)
err = 1
if err:
return 1
# likely encoding used for command-line arguments
try:
locale = __import__('locale') # due to submodule of the same name
likely_encoding = locale.getpreferredencoding()
except Exception:
likely_encoding = None
buildername = None
force_all = freshenv = warningiserror = use_pdb = False
show_traceback = False
verbosity = 0
parallel = 0
status = sys.stdout
warning = sys.stderr
error = sys.stderr
warnfile = None
confoverrides = {}
tags = []
doctreedir = path.join(outdir, '.doctrees')
for opt, val in opts:
if opt == '-b':
buildername = val
elif opt == '-a':
if 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 = abspath(val)
elif opt == '-c':
confdir = abspath(val)
if not path.isfile(path.join(confdir, 'conf.py')):
print('Error: Configuration directory doesn\'t contain conf.py file.',
file=sys.stderr)
return 1
elif opt == '-C':
confdir = None
elif opt == '-D':
try:
key, val = val.split('=')
except ValueError:
print('Error: -D option argument must be in the form name=value.',
file=sys.stderr)
return 1
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides[key] = val
elif opt == '-A':
try:
key, val = val.split('=')
except ValueError:
print('Error: -A option argument must be in the form name=value.',
file=sys.stderr)
return 1
try:
val = int(val)
except ValueError:
if likely_encoding and isinstance(val, binary_type):
try:
val = val.decode(likely_encoding)
except UnicodeError:
pass
confoverrides['html_context.%s' % key] = val
elif opt == '-n':
confoverrides['nitpicky'] = True
elif opt == '-N':
nocolor()
elif opt == '-E':
freshenv = True
elif opt == '-q':
status = None
elif opt == '-Q':
status = None
warning = None
elif opt == '-W':
warningiserror = True
elif opt == '-w':
warnfile = val
elif opt == '-P':
use_pdb = True
elif opt == '-T':
show_traceback = True
elif opt == '-v':
verbosity += 1
show_traceback = True
elif opt == '-j':
try:
parallel = int(val)
except ValueError:
print('Error: -j option argument must be an integer.',
file=sys.stderr)
return 1
if warning and warnfile:
warnfp = open(warnfile, 'w')
warning = Tee(warning, warnfp)
error = warning
if not path.isdir(outdir):
if status:
print('Making output directory...', file=status)
os.makedirs(outdir)
app = None
try:
app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername,
confoverrides, status, warning, freshenv,
warningiserror, tags, verbosity, parallel)
app.build(force_all, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as err:
if use_pdb:
import pdb
print(red('Exception occurred while building, starting debugger:'),
file=error)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
print(file=error)
if show_traceback:
traceback.print_exc(None, error)
print(file=error)
if isinstance(err, KeyboardInterrupt):
print('interrupted!', file=error)
elif isinstance(err, SystemMessage):
print(red('reST markup error:'), file=error)
print(terminal_safe(err.args[0]), file=error)
elif isinstance(err, SphinxError):
print(red('%s:' % err.category), file=error)
print(terminal_safe(text_type(err)), file=error)
elif isinstance(err, UnicodeError):
print(red('Encoding error:'), file=error)
print(terminal_safe(text_type(err)), file=error)
tbpath = save_traceback(app)
print(red('The full traceback has been saved in %s, if you want '
'to report the issue to the developers.' % tbpath),
file=error)
else:
print(red('Exception occurred:'), file=error)
print(format_exception_cut_frames().rstrip(), file=error)
tbpath = save_traceback(app)
print(red('The full traceback has been saved in %s, if you '
'want to report the issue to the developers.' % tbpath),
file=error)
print('Please also report this if it was a user error, so '
'that a better error message can be provided next time.',
file=error)
print('A bug report can be filed in the tracker at '
'<https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!',
file=error)
return 1
def main(argv: List[str] = sys.argv[1:]) -> int:
sphinx.locale.setlocale(locale.LC_ALL, '')
sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
if not color_terminal():
nocolor()
# parse options
parser = get_parser()
try:
args = parser.parse_args(argv)
except SystemExit as err:
return err.code
d = vars(args)
# delete None or False value
d = {k: v for k, v in d.items() if v is not None}
# handle use of CSV-style extension values
d.setdefault('extensions', [])
for ext in d['extensions'][:]:
if ',' in ext:
d['extensions'].remove(ext)
d['extensions'].extend(ext.split(','))
try:
if 'quiet' in d:
if not {'project', 'author'}.issubset(d):
print(
__('"quiet" is specified, but any of "project" or '
'"author" is not specified.'))
return 1
if {'quiet', 'project', 'author'}.issubset(d):
# quiet mode with all required params satisfied, use default
d.setdefault('version', '')
d.setdefault('release', d['version'])
d2 = DEFAULTS.copy()
d2.update(d)
d = d2
if not valid_dir(d):
print()
print(
bold(
__('Error: specified path is not a directory, or sphinx'
' files already exist.')))
print(
__('sphinx-quickstart only generate into a empty directory.'
' Please specify a new root path.'))
return 1
else:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print()
print('[Interrupted.]')
return 130 # 128 + SIGINT
for variable in d.get('variables', []):
try:
name, value = variable.split('=')
d[name] = value
except ValueError:
print(__('Invalid template variable: %s') % variable)
generate(d, overwrite=False, templatedir=args.templatedir)
return 0
def main(argv=sys.argv):
# type: (List[str]) -> int
if not color_terminal():
nocolor()
parser = optparse.OptionParser(USAGE, epilog=EPILOG,
version='Sphinx v%s' % __display_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.add_option('--extensions', metavar='EXTENSIONS', dest='extensions',
action='append', help='enable extensions')
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')
group.add_option('-M', '--no-use-make-mode', action='store_false', dest='make_mode',
help='not use make-mode for Makefile/make.bat')
group.add_option('-m', '--use-make-mode', action='store_true', dest='make_mode',
default=True,
help='use make-mode for Makefile/make.bat')
group = parser.add_option_group('Project templating')
group.add_option('-t', '--templatedir', metavar='TEMPLATEDIR', dest='templatedir',
help='template directory for template files')
group.add_option('-d', metavar='NAME=VALUE', action='append', dest='variables',
help='define a template variable')
# parse options
try:
opts, args = parser.parse_args(argv[1:])
except SystemExit as err:
return err.code
if len(args) > 0:
opts.ensure_value('path', args[0])
d = vars(opts)
# delete None or False value
d = dict((k, v) for k, v in d.items() if not (v is None or v is False))
try:
if 'quiet' in d:
if not set(['project', 'author']).issubset(d):
print('''"quiet" is specified, but any of "project" or \
"author" is not specified.''')
return 1
if set(['quiet', 'project', 'author']).issubset(d):
# quiet mode with all required params satisfied, use default
d.setdefault('version', '')
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 not valid_dir(d):
print()
print(bold('Error: specified path is not a directory, or sphinx'
' files already exist.'))
print('sphinx-quickstart only generate into a empty directory.'
' Please specify a new root path.')
return 1
else:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print()
print('[Interrupted.]')
return 130 # 128 + SIGINT
# decode values in d if value is a Python string literal
for key, value in d.items():
if isinstance(value, binary_type):
d[key] = term_decode(value)
# parse extensions list
d.setdefault('extensions', [])
for ext in d['extensions'][:]:
if ',' in ext:
d['extensions'].remove(ext)
for modname in ext.split(','):
d['extensions'].append(modname)
for variable in d.get('variables', []):
try:
name, value = variable.split('=')
d[name] = value
except ValueError:
print('Invalid template variable: %s' % variable)
generate(d, templatedir=opts.templatedir)
return 0
def main(argv=sys.argv):
if not color_terminal():
nocolor()
parser = optparse.OptionParser(USAGE,
epilog=EPILOG,
version='Sphinx v%s' % __display_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')
group.add_option('-M',
'--no-use-make-mode',
action='store_false',
dest='make_mode',
help='not use make-mode for Makefile/make.bat')
group.add_option('-m',
'--use-make-mode',
action='store_true',
dest='make_mode',
default=True,
help='use make-mode for Makefile/make.bat')
# parse options
try:
opts, args = parser.parse_args(argv[1:])
except SystemExit as err:
return err.code
if len(args) > 0:
opts.ensure_value('path', args[0])
d = vars(opts)
# delete None or False value
d = dict((k, v) for k, v in d.items() if not (v is None or v is False))
try:
if 'quiet' in d:
if not set(['project', 'author']).issubset(d):
print('''"quiet" is specified, but any of "project" or \
"author" is not specified.''')
return 1
if set(['quiet', 'project', 'author']).issubset(d):
# quiet mode with all required params satisfied, use default
d.setdefault('version', '')
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 not valid_dir(d):
print()
print(
bold('Error: specified path is not a directory, or sphinx'
' files already exist.'))
print('sphinx-quickstart only generate into a empty directory.'
' Please specify a new root path.')
return 1
else:
ask_user(d)
except (KeyboardInterrupt, EOFError):
print()
print('[Interrupted.]')
return 130 # 128 + SIGINT
# decode values in d if value is a Python string literal
for key, value in d.items():
if isinstance(value, binary_type):
d[key] = term_decode(value)
generate(d)
