diff --git a/CHANGES b/CHANGES index e06a6faba..8789b53af 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,9 @@ Deprecated Features added -------------- +* #4271: sphinx-build supports an option called ``-j auto`` to adjust numbers of + processes automatically. + Bugs fixed ---------- diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 46f213989..fdd0d36c2 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -143,11 +143,15 @@ Options Distribute the build over *N* processes in parallel, to make building on multiprocessor machines more effective. Note that not all parts and not all - builders of Sphinx can be parallelized. + builders of Sphinx can be parallelized. If ``auto`` argument is given, + Sphinx uses the number of CPUs as *N*. .. versionadded:: 1.2 This option should be considered *experimental*. + .. versionchanged:: 1.7 + Support ``auto`` argument. + .. option:: -c path Don't look for the :file:`conf.py` in the source directory, but use the given diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 779ba142d..4cf5a07ef 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -11,6 +11,7 @@ from __future__ import print_function import argparse +import multiprocessing import sys import traceback from os import path @@ -83,6 +84,23 @@ def handle_exception(app, args, exception, stderr=sys.stderr): file=stderr) +def jobs_argument(value): + # type: (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(): # type: () -> argparse.ArgumentParser parser = argparse.ArgumentParser( @@ -129,10 +147,9 @@ files can be built by specifying individual filenames. group.add_argument('-d', metavar='PATH', dest='doctreedir', help='path for the cached environment and doctree ' 'files (default: OUTPUTDIR/.doctrees)') - group.add_argument('-j', metavar='N', default=1, type=int, dest='jobs', + group.add_argument('-j', metavar='N', default=1, type=jobs_argument, dest='jobs', help='build in parallel with N processes where ' - 'possible') - + '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 '