346 lines
14 KiB
Python
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:]))
|