usse/scrape/venv/lib/python3.10/site-packages/sphinx/cmd/build.py
2023-12-22 15:26:01 +01:00

346 lines
14 KiB
Python

"""Build documentation from a provided source."""
from __future__ import annotations
import argparse
import bdb
import contextlib
import locale
import multiprocessing
import os
import pdb # NoQA: T100
import sys
import traceback
from os import path
from typing import TYPE_CHECKING, Any, TextIO
from docutils.utils import SystemMessage
import sphinx.locale
from sphinx import __display_version__
from sphinx.application import Sphinx
from sphinx.errors import SphinxError, SphinxParallelError
from sphinx.locale import __
from sphinx.util import Tee
from sphinx.util.console import ( # type: ignore[attr-defined]
color_terminal,
nocolor,
red,
terminal_safe,
)
from sphinx.util.docutils import docutils_namespace, patch_docutils
from sphinx.util.exceptions import format_exception_cut_frames, save_traceback
from sphinx.util.osutil import ensuredir
if TYPE_CHECKING:
from collections.abc import Sequence
def handle_exception(
app: Sphinx | None, args: Any, exception: BaseException, stderr: TextIO = sys.stderr,
) -> None:
if isinstance(exception, bdb.BdbQuit):
return
if args.pdb:
print(red(__('Exception occurred while building, starting debugger:')),
file=stderr)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
print(file=stderr)
if args.verbosity or args.traceback:
exc = sys.exc_info()[1]
if isinstance(exc, SphinxParallelError):
exc_format = '(Error in parallel process)\n' + exc.traceback
print(exc_format, file=stderr)
else:
traceback.print_exc(None, stderr)
print(file=stderr)
if isinstance(exception, KeyboardInterrupt):
print(__('Interrupted!'), file=stderr)
elif isinstance(exception, SystemMessage):
print(red(__('reST markup error:')), file=stderr)
print(terminal_safe(exception.args[0]), file=stderr)
elif isinstance(exception, SphinxError):
print(red('%s:' % exception.category), file=stderr)
print(str(exception), file=stderr)
elif isinstance(exception, UnicodeError):
print(red(__('Encoding error:')), file=stderr)
print(terminal_safe(str(exception)), file=stderr)
tbpath = save_traceback(app, exception)
print(red(__('The full traceback has been saved in %s, if you want '
'to report the issue to the developers.') % tbpath),
file=stderr)
elif isinstance(exception, RuntimeError) and 'recursion depth' in str(exception):
print(red(__('Recursion error:')), file=stderr)
print(terminal_safe(str(exception)), file=stderr)
print(file=stderr)
print(__('This can happen with very large or deeply nested source '
'files. You can carefully increase the default Python '
'recursion limit of 1000 in conf.py with e.g.:'), file=stderr)
print(' import sys; sys.setrecursionlimit(1500)', file=stderr)
else:
print(red(__('Exception occurred:')), file=stderr)
print(format_exception_cut_frames().rstrip(), file=stderr)
tbpath = save_traceback(app, exception)
print(red(__('The full traceback has been saved in %s, if you '
'want to report the issue to the developers.') % tbpath),
file=stderr)
print(__('Please also report this if it was a user error, so '
'that a better error message can be provided next time.'),
file=stderr)
print(__('A bug report can be filed in the tracker at '
'<https://github.com/sphinx-doc/sphinx/issues>. Thanks!'),
file=stderr)
def jobs_argument(value: str) -> int:
"""
Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can
be expanded to handle other special scaling requests, such as setting job count
to cpu_count.
"""
if value == 'auto':
return multiprocessing.cpu_count()
else:
jobs = int(value)
if jobs <= 0:
raise argparse.ArgumentTypeError(__('job number should be a positive number'))
else:
return jobs
def get_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
usage='%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]',
epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
description=__("""
Generate documentation from source files.
sphinx-build generates documentation from the files in SOURCEDIR and places it
in OUTPUTDIR. It looks for 'conf.py' in SOURCEDIR for the configuration
settings. The 'sphinx-quickstart' tool may be used to generate template files,
including 'conf.py'
sphinx-build can create documentation in different formats. A format is
selected by specifying the builder name on the command line; it defaults to
HTML. Builders can also perform other tasks related to documentation
processing.
By default, everything that is outdated is built. Output only for selected
files can be built by specifying individual filenames.
"""))
parser.add_argument('--version', action='version', dest='show_version',
version='%%(prog)s %s' % __display_version__)
parser.add_argument('sourcedir',
help=__('path to documentation source files'))
parser.add_argument('outputdir',
help=__('path to output directory'))
parser.add_argument('filenames', nargs='*',
help=__('a list of specific files to rebuild. Ignored '
'if -a is specified'))
group = parser.add_argument_group(__('general options'))
group.add_argument('-b', metavar='BUILDER', dest='builder',
default='html',
help=__('builder to use (default: html)'))
group.add_argument('-a', action='store_true', dest='force_all',
help=__('write all files (default: only write new and '
'changed files)'))
group.add_argument('-E', action='store_true', dest='freshenv',
help=__("don't use a saved environment, always read "
'all files'))
group.add_argument('-d', metavar='PATH', dest='doctreedir',
help=__('path for the cached environment and doctree '
'files (default: OUTPUTDIR/.doctrees)'))
group.add_argument('-j', '--jobs', metavar='N', default=1, type=jobs_argument,
dest='jobs',
help=__('build in parallel with N processes where '
'possible (special value "auto" will set N to cpu-count)'))
group = parser.add_argument_group('build configuration options')
group.add_argument('-c', metavar='PATH', dest='confdir',
help=__('path where configuration file (conf.py) is '
'located (default: same as SOURCEDIR)'))
group.add_argument('-C', action='store_true', dest='noconfig',
help=__('use no config file at all, only -D options'))
group.add_argument('-D', metavar='setting=value', action='append',
dest='define', default=[],
help=__('override a setting in configuration file'))
group.add_argument('-A', metavar='name=value', action='append',
dest='htmldefine', default=[],
help=__('pass a value into HTML templates'))
group.add_argument('-t', metavar='TAG', action='append',
dest='tags', default=[],
help=__('define tag: include "only" blocks with TAG'))
group.add_argument('-n', action='store_true', dest='nitpicky',
help=__('nit-picky mode, warn about all missing '
'references'))
group = parser.add_argument_group(__('console output options'))
group.add_argument('-v', action='count', dest='verbosity', default=0,
help=__('increase verbosity (can be repeated)'))
group.add_argument('-q', action='store_true', dest='quiet',
help=__('no output on stdout, just warnings on stderr'))
group.add_argument('-Q', action='store_true', dest='really_quiet',
help=__('no output at all, not even warnings'))
group.add_argument('--color', action='store_const', const='yes',
default='auto',
help=__('do emit colored output (default: auto-detect)'))
group.add_argument('-N', '--no-color', dest='color', action='store_const',
const='no',
help=__('do not emit colored output (default: '
'auto-detect)'))
group.add_argument('-w', metavar='FILE', dest='warnfile',
help=__('write warnings (and errors) to given file'))
group.add_argument('-W', action='store_true', dest='warningiserror',
help=__('turn warnings into errors'))
group.add_argument('--keep-going', action='store_true', dest='keep_going',
help=__("with -W, keep going when getting warnings"))
group.add_argument('-T', action='store_true', dest='traceback',
help=__('show full traceback on exception'))
group.add_argument('-P', action='store_true', dest='pdb',
help=__('run Pdb on exception'))
return parser
def make_main(argv: Sequence[str]) -> int:
"""Sphinx build "make mode" entry."""
from sphinx.cmd import make_mode
return make_mode.run_make_mode(argv[1:])
def _parse_arguments(argv: Sequence[str]) -> argparse.Namespace:
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')
if args.force_all and args.filenames:
parser.error(__('cannot combine -a option and filenames'))
if args.color == 'no' or (args.color == 'auto' and not color_terminal()):
nocolor()
status: TextIO | None = sys.stdout
warning: TextIO | None = sys.stderr
error = sys.stderr
if args.quiet:
status = None
if args.really_quiet:
status = warning = None
if warning and args.warnfile:
try:
warnfile = path.abspath(args.warnfile)
ensuredir(path.dirname(warnfile))
warnfp = open(args.warnfile, 'w', encoding="utf-8") # NoQA: SIM115
except Exception as exc:
parser.error(__('cannot open warning file %r: %s') % (
args.warnfile, exc))
warning = Tee(warning, warnfp) # type: ignore[assignment]
error = warning
args.status = status
args.warning = warning
args.error = error
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'))
with contextlib.suppress(ValueError):
val = int(val)
confoverrides['html_context.%s' % key] = val
if args.nitpicky:
confoverrides['nitpicky'] = True
args.confoverrides = confoverrides
return args
def build_main(argv: Sequence[str]) -> int:
"""Sphinx build "main" command-line entry."""
args = _parse_arguments(argv)
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, args.confoverrides, args.status,
args.warning, args.freshenv, args.warningiserror,
args.tags, args.verbosity, args.jobs, args.keep_going,
args.pdb)
app.build(args.force_all, args.filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
handle_exception(app, args, exc, args.error)
return 2
def _bug_report_info() -> int:
from platform import platform, python_implementation
import docutils
import jinja2
import pygments
print('Please paste all output below into the bug report template\n\n')
print('```text')
print(f'Platform: {sys.platform}; ({platform()})')
print(f'Python version: {sys.version})')
print(f'Python implementation: {python_implementation()}')
print(f'Sphinx version: {sphinx.__display_version__}')
print(f'Docutils version: {docutils.__version__}')
print(f'Jinja2 version: {jinja2.__version__}')
print(f'Pygments version: {pygments.__version__}')
print('```')
return 0
def main(argv: Sequence[str] = (), /) -> int:
locale.setlocale(locale.LC_ALL, '')
sphinx.locale.init_console()
if not argv:
argv = sys.argv[1:]
# Allow calling as 'python -m sphinx build …'
if argv[:1] == ['build']:
argv = argv[1:]
if argv[:1] == ['--bug-report']:
return _bug_report_info()
if argv[:1] == ['-M']:
return make_main(argv)
else:
return build_main(argv)
if __name__ == '__main__':
raise SystemExit(main(sys.argv[1:]))